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This publication describes the concepts, features 
and implementation of TSO, a general purpose 
time-sharing facility operating under the MVT 
configuration of the control program. This manual 
is intended for those who design, generate, and 
maintain a TSO installation. 


This publication discusses: 
e The general capabilities and advantages of TSO. 


e The command language, programming languages 
and system facilities available to a TSO terminal 
user. 


e The system elements added to MVT for TSO. 


e The generation and maintainance of a system 
with TSO. 


Preface 


There are three appendixes: 
e A list of the TSO commands by function. 
¢ A list of the Time Sharing Driver Entry Codes. 


e A list of Message Control Program diagnostic 
messages. 


There is also a bibliography of related reading and 
an index. 


The prerequisite publication is: 


IBM System/360 Operating System: MVT Guide, 
GC28-6720. 
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| Summary of Amendments 
for GC28-6698-6 
OS Release 21.7 


TCAM Level 4 


Changes are made to the macro instructions for 
generating a TSO Message Control Program to support 
TCAM Level 4. 


New Device Support 


The 3270 Information Display System is supported as a 
terminal device. 


Message Control Program Diagnostics 


A section describing the diagnostic messages generated 
by the macro instructions which create a message control 
program for TSO has been added. 


Summary of Amendments 

for GC28-6698-4 

as Updated by GN28-2519 
(Equivalent to GC28-6698-5) 
Component Release 360S-OS-586 


Dynamic Specification of DCB Parameters 


The ATTRIB command, which provides the TSO user 
with the capability for assigning data set attributes (DCB 
parameters) dynamically from the terminal, has been 
added. 


Installation Messages 


The section describing messages which require 
installation action has been removed. The information 
may be found in IBM System/360 Operating System: 
Messages and Codes, GC28-6631. 


Program Product Information 
Specific information about IBM Program Products has 
been removed and a reference has been added to the 


Bibliography pointing to a general information source 
for Program Product information. 


Miscellaneous Changes 


Minor changes have been made throughout the 
publication to correct and clarify the information 
presented. 
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Summary of Amendments 
for GC28-6698-4 
OS Release 21 


Publications Change 


Information describing job priorities, dispatching, and 
classes, formerly in IBM System/360 Operating System: 
Concepts and Facilities, GC28-6535, is now contained in 


IBM System/360 Operating System: Introduction, GC28-6534. 


SVC Restrictions 


Programming Change 


SVC 93 (TGET/TPUT) can be used for certain 
background purposes. 


Dynamic Allocation 


Programming Change 


A dynamically allocated data set uses 50 tracks for a 
primary allocation and 10 for secondary allocation. 


Time Sharing Driver Parameters 


Rewritten section 


The description of the Time Sharing Driver start 
parameters has been rewritten to show dependencies 
between parameters. 
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Tuning the TSO system 


New Section 

A new Section has been added to describe TSO tuning 
techniques. 

Bibliography 

New Section 


A discussion of related reading, formerly in the Preface, 
has been moved to the Bibliography and rewritten. 


Swap Data Sets 
Clarification 


Swap data Sets must be allocated along cylinder 
boundaries. 


Introduction 


The IBM System/360 Operating System Time Sharing Option (TSO) adds general purpose time 
sharing to the facilities already available through the MVT configuration of the control program. As 
a result, the system provides a number of new capabilities: 


It gives users access to the system through a command language which is entered at remote 
terminals -- typewriter-like keyboard-printer or keyboard-screen devices connected through 
telephone or other communication lines to the computer. 


It gives those who may not be programmers the use of data entry, editing, and retrieval facilities. 


It makes the facilities of the operating system available to programmers at remote terminals to 
develop, test, and execute programs conveniently, without the job turnaround delays typical of 
batch processing. Both terminal-oriented and batch programs can be developed at terminals. 


It allows the management of an installation to dynamically control the use of the system’s 
resources from a terminal. 


It creates a time-sharing environment for terminal-oriented applications. Some applications, such 
as problem-solving languages, terminal-oriented compilers, and text-editing facilities, are available 
as IBM Program Products. Installations can add others suited to their particular needs. 


A major consideration in the design of TSO is ease of use. The way in which a user 


communicates with the system can be kept simple to encourage people who may not be 
programmers to take advantage of the speed and versatility of a computing system to solve their 
problems. There are four ways in which TSO achieves this goal: 


The physical medium is easy to use. Most users are already familiar with the conventional 
typewriter keyboard. Information is easy to enter through the terminal’s typewriter-like keyboard, 
and no complex procedures are required to obtain output from the computer. 


The way in which a terminal user defines his work is uncomplicated. He enters commands which 
resemble English language words to describe the general function he wants to accomplish. If the 
user chooses, he can create his own commands and command system. 


If a user doesn’t know how to define his work to the system, he can type HELP and receive 
information pertinent to the type of operation he is trying to perform. In most cases, he doesn’t 
need to enter detailed parameters describing every aspect of the work he is doing; the system 
uses default values that are appropriate for most jobs. If he fails to provide parameters the system 
needs to do the work he requested, the system will ask him for the missing information, item by 
item, by “prompting” him for it in a conversational way. 


The system keeps the terminal user aware of what is happening, so he knows what to do next. 
He “‘converses”’ with the system on a step-by-step basis. The system lets him know when it is 
ready to accept input from him, and it tells him immediately when there has been a change in the 
status of his program. If the user receives a message he doesn’t understand, he can request more 
information about the situation simply by typing a question mark. The messages he receives use 
uncomplicated language to describe the situation. When the messages become familiar to him, he 
may request the system to use the abbreviated messages that are available with some of the 
programming languages. 
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Advantages of a Time Sharing System 


In a simple batch processing system, one job at a time has access to the resources of the system 
(main storage, the central processing unit, and I/O equipment). A programmer’s job is loaded into 
the computer and its operation is controlled by the system operator. The job acquires the resources 
it needs as it runs to completion; resources the job doesn’t need are unused. When the job is 
finished, results are produced, a new job is loaded and executed, and the output for the completed 
job (for example, a printout) is sent to the programmer. An inherent problem with this type of 
processing is turnaround time, the elapsed time between the submission of a job to the computer 
center for processing and the return of results to the programmer. Another problem is the inefficient 
use of resources. 


In a multiprogramming system (e.g., a system that operates under the control of the MVT 
configuration of the System/360 Operating System), several jobs share the resources of the system 
concurrently, so the use of resources is much more efficient. Although jobs are processed faster, the 
operator at the system console still controls the system, and the programmer still must wait for 
results to be returned to him. 


A time sharing system reduces delays in receiving results. A larger number of jobs share the 
resources of the system concurrently, and the execution of each job is controlled primarily by a 
remote terminal user. Thus, time sharing can be defined as the shared, conversational, and 
concurrent use of a computing system by a number of users at remote terminals. 


The system resources shared by the time sharing jobs (foreground jobs) entered from the 
terminals are also shared by batch jobs (background jobs) that are being processed at the same 
time. Each foreground main storage region handles many active foreground jobs, although only one 
job is actually in the region at any moment in time. A foreground job is assigned to a main storage 
region and has access to the system’s resources for a short period of time called a time slice. The 
other foreground jobs assigned to that region are saved on auxiliary storage while the job being 
executed in main storage receives a time slice. 


At the end of the job’s time slice, or if the job enters the wait state for terminal I/O, the main 
storage image of the job (that is, programs, work areas, and associated control blocks) is stored on a 
direct access device and another job is brought into the same region of main storage and given a 
time slice. TSO schedules a similar time slice for each ready foreground job. The apportionment and 
duration of time slices is disussed in detail in the ‘System Summary”’ section of this manual. 


The process of copying job images back and forth between main and auxiliary storage is called 
swapping. Writing an image to auxiliary storage is a swap out; reading one into main storage is a swap 
in. 


All foreground jobs are assigned the same priority. The order in which foreground and 
background jobs are processed is determined by the operating system task dispatcher and the TSO 
control routines. Job priorities, job classes, and the dispatching of tasks are discussed in IBM 
System/360 Operating System: Introduction, GC28-6534. 


The apportionment of slices of processing time to foreground jobs is not apparent to a terminal 
user. At the terminal, the response of the system to requests for action is fast enough so that he has 
the impression that he is the sole user. As far as the user is concerned the distinctive feature of a 
time-sharing system is the way in which it “‘converses’”’ or interacts on a step-by-step basis with him 
as he does his work. He is prompted for information the system needs to execute his job, he 
receives immediate response to his requests for action, and he is notified immediately of errors the 
system detects, so that he can take corrective action at once. 


In general then, a time-sharing system differs from a batch processing system in three ways: 
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1. A terminal user concurrently shares the resources of a computing system with other terminal 
users. 


2. A terminal user can enter his problem statements and other input into the system as he develops 
them, and he receives immediate results. Thus the problem of turnaround time (the amount of 
time between when he submits his job for processing and when he receives results) inherent with 
batch job operations is greatly reduced. 


3. A terminal user is constantly aware of the progress of his job. He requests results from the 
system one step at a time, he is prompted for any additional information the system requires, he 
receives immediate notification of the status of his work, and he is apprised of errors as soon as 
the system detects them. The terminal user can change his problem statements or correct errors 
immediately after entering each statement or at any time during the current terminal session. 
Thus, he minimizes the need for reruns. 


Using a Terminal 


A terminal session is designed to be an uncomplicated process for a terminal user: he identifies 
himself to the system and then issues commands to request work from the system. As the session 
progresses, the user has a variety of aids available at the terminal which he can use if he encounters 
any difficulties. 


Commands specifically tailored to an installation’s needs can be written and added to the 
command language or used to replace IBM-supplied commands. 


Starting and Stopping a Terminal Session 


When the user has some work to perform with the system, he dials the system number if he has a 
terminal on a switched line, or he turns the power on if he has a terminal on a non-switched line. A 
switched line is one in which the connection between the computer and a terminal is established by 
dialing the system’s number from the terminal. A non-switched line is one with a connection 
between the computer and a terminal. With an IBM 2741 terminal or an IBM 1050 terminal, the 
system responds by unlocking the keyboard. In any case, the user identifies himself by entering 
“LOGON” and one or more of the following fields: 


e A user identification, for example, the user’s name or initials, which the system will use to identify 
his programs and data sets. 


e A password, assigned by his installation, usually known only to the user and the system manager. 


e An account number, which defines the account in which his system usage totals are to be 
accumulated. 


e A LOGON procedure name, which identifies a cataloged procedure that specifies what system 
resources he will be using. 


The user may omit the last three fields if the system manager has defined only one account number 
and LOGON procedure for him and no password is used. 


The LOGON processor verifies that the user is an authorized TSO user, then checks the 
password, if it is required, and account number in a record it keeps of user attributes, called the 
User Attributes Data Set (UADS). From the attributes, the LOGON command operands, and a 
LOGON cataloged procedure, the system builds a user profile, which is used to control the 
processing of his job. The system assigns the user’s job to a time-sharing (foreground) region of 
main storage and allocates other resources, such as auxiliary storage space and user data sets 
according to the LOGON procedure. 
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LOGON marks the start of a terminal session. When the user completes his work, he enters 
“LOGOFF” to end the session. The system then updates his job’s system use totals, releases 
resources allocated to it, and releases the terminal from TSO. A session is also terminated any time 
the terminal user enters LOGON to start a new session. In this case, the old session is terminated 
and a new one is begun; the terminal is not released in the process. 


Working at the Terminal 


The user enters commands to define and execute his work at the terminal. He enters a command by 
typing a command name, such as EDIT and possibly some additional operands. The system finds the 
appropriate command processor--a load module in a command library--and brings it into the 
foreground region assigned to the user for execution. For example, in response to entering the EDIT 
command, the system brings in the EDIT command processor, the data handling routine used to 
create and update data sets. 


If a user does not enter all the operands associated with a particular command name, default 
values are assumed where possible. If necessary operands are missing, the system prompts the user 
for them with a message such as “ENTER DATA SET NAME.” The user can reply with the missing 
value, or enter a question mark for a further explanation of what the system needs. If the user 
chooses, he can specify that prompting messages be suppressed. 


A terminal user can also receive assistance through the HELP facility. He can request information 
regarding the syntax, operands, or function of any command, subcommand, or operand. If he enters 
HELP followed by a command name, he receives an explanation of the command and the operands 
required with it. HELP followed by a subcommand name furnishes an explanation of the 
subcommand if the user is working with the command at that time. Entering HELP by itself returns 
a description of the command language, a list of the commands, and an explanation of how to use 
HELP to obtain further information. 


During a typical session, the user enters a series of commands to define and perform his work. If 
the sequence is one that is used often, he can store the sequence in a data set and then execute the 
sequence whenever he needs it by entering the EXEC commands. 


The commands provided with the system handle data and program entry, program invocation in 
either the foreground or the background, program testing, data management, and session and system 
control. IBM Program Products are available to support problem solving, data manipulation, and text 
formatting, to provide terminal-oriented language processors, and to make these processors more 
convenient to use from the terminal. 


System Configuration 


TSO is an extension of the MVT configuration of the control program on System/360 Models 50 
through 195, or System/370 Models 145, 155, and 165. TSO also operates with the Model 65 
Multiprocessing (M65MP) configuration. The minimum machine configuration for System/360 
models must include 384K of main storage, the required I/O devices for MVT, plus at least one 
each of the following: 


e A terminal (IBM 1050, 2741, 2260 Local or Remote, 2265, or Teletype! Model 33 or 35 KSR 
and ASR). 


e A transmission control unit (IBM 2701, 2702, or 2703), unless all terminals are locally attached 
2260 Display Stations. 


Trademark of Teletype Corporation, Skokie, Illinois. 
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e Sufficient direct access storage space (IBM 2301, 2311, 2303, 2305, 2314, or 3330) for 
command libraries and system data sets. 


e Sufficient direct access storage space for swap data sets. 


In a System/360 with 384K of main storage, TSO is, in effect, a "dedicated" time sharing system. 
In other words, with 384K the system can run as a time sharing system or as a batch job processing 
system, but not both at the same time. To run both time sharing and batch jobs concurrently or to 
execute on M65MP or System/370 models, at least 512K of main storage is required. At least 128K 
of main storage is required for system generation. 


Terminals 


Some remote terminal suitable for interactive applications have keyboards for entering input data 
and either typewriter-like printers or display screens. A remote terminal incorporates or is attached 
to a control unit. The control unit is in turn connected to the system by either of two ways: 


e Through a device such as a data set to a dialed (switched) line to the system. 
e Through either a direct or a leased line to the system. 


At the computer site the communication line connects to a Transmission Control Unit, which in 
turn is attached to one of the computer system’s multiplexor channels. The IBM 2260 Display 
Station can be an exception to this general configuration. Its control unit, the IBM 2848 Display 
Control, can be attached directly to a multiplexor or selector channel. This mode of operation is 
called local attachment. 


TSO uses the Telecommunications Access Method (TCAM) for terminal access. TSO provides 
terminal handling programs for the following terminals: 


e IBM 2741 Communication Terminal. 

e IBM 1050 Printer-Keyboard. 

e Teletype! Model 33 and 35 KSR or ASR. (Paper tape is not supported with Teletype!.) 
e IBM 2260, 3270, and 2265 Display Stations. 


The IBM 2741 Receive Interruption Feature and the Transmit Interruption Feature are 
recommended for use with the 2741. These features are described in the publication IBM 2741 
Communications Terminal. The Transmit Interrupt, Receive Interrupt, and Text-Timeout Suppression 
features are recommended for use with the IBM 1050. 1050 multidrop is not supported. These 
features are described in the publication IBM 1050 System Summary. Note that some of these 
features are not available through the IBM 2701 Data Adapter Unit.2 


Transmission Control Unit 


TSO requires at least one of the following transmission control units to handle terminal 
communications: 


e IBM 2701 Data Adapter Unit. 
e IBM 2702 Transmission Control. 
e IBM 2703 Transmission Control. 


2Terminals which are equivalent to those explicitly supported may also function satisfactorily. The customer is 
responsible for establishing equivalency. IBM assumes no responsibility for the impact that any changes to the 
IBM-supplied products or programs may have on such terminals. 
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The Terminal Interruption Features are recommended for use with the 2702 and 2703 transmission 
control units and must be present if the terminals are to use the features. These units are described 
in the following publications. 


e IBM 2701 Data Adapter Unit, Component Description, GA22-6864. 
e IBM System/360 Component Description, IBM 2702 Transmission Control, GA22-6846. 


e IBM 2703 Transmission Control, Component Description, GA27-2703. 


Swap Data Set Devices 


The process of copying images back and forth between main and auxiliary storage is called swapping. 
Writing an image to auxiliary storage is a swap out; reading one into main storage is a swap in. The 
pre-formatted data sets into which jobs are written are called swap data sets. A swap data set is 
divided into swap allocation units, each of which consists of a device-dependent number of 2048-byte 
records. An integral number of swap allocation units, not necessarily contiguous, are assigned to 
each job to contain the swapped out image of the job. 


If there is more than one foreground region, they share the available swap data sets, but the cycle 
of swapping for each region 1s essentially independent of other regions. However, the system avoids 
queueing on swap data sets if possible. 


TSO requires sufficient storage capacity on one or more of the following for swap data sets: 


e IBM 2301 Drum Storage. 

e IBM 2303 Drum Storage. 

« IBM 2305 Fixed Head Storage, Model 1 or 2. 

e IBM 2314/2319 Direct Access Storage Facility. 
e IBM 3330 Disk Storage Facility. 


See the ‘Storage Estimates” section of this publication for information on swap data set sizes. 


The record overflow feature is required for the devices used to store the swap data sets. One or 
more data sets on any of the above devices can be used for swap data sets. 


The direct access storage space required for the swapped data may be divided among the devices 
listed above in either of two ways. The user may specify that swapped data be distributed serially 
among a hierarchy of data sets, or he may specify parallel distribution of data onto two or more 
devices. With serial distribution, the first data set in the hierarchy is filled with swapped data, and 
then the next data set in the hierarchy is used. For example, a drum, because of its higher access 
speed, could be assigned as the first unit in the hierarchy, with a 2314 assigned to receive any 
overflow of swapped data. 


With the parallel distribution scheme, two or more devices are used concurrently to receive swap 
data sets. Identical device types must be used with parallel swapping. The exact order in which data 
sets are written on either of the devices is determined by the system, based on the I/O activity 
taking place in the channel at the time of a swap out. For example, if the two data sets are on 
devices on separate channels, swap performance improves substantially. 


Before a terminal job can be swapped out of main storage, activity associated with the job must 
be brought to an orderly halt. The halt must be performed in such a way that the job is not aware 
of it, and information must be saved to restart the job when its next time slice is scheduled. The 
orderly suspension of a job’s activity before a swap out is called quiescing the job. Quiescing 
includes the removal of the majority of the control blocks associated with the job from the system 
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queues so they can be written to the swap data set along with the contents of the main storage 
region assigned to the job. 


The Relationship of TSO to the Operating System 


For the data processing center, TSO is compatible with operating system standard formats and 
services, while providing the flexibility needed for various time sharing and terminal-based 
applications. 


TSO is not necessarily intended to be used as a dedicated time-sharing system, that is, a system 
on which only time-sharing operations take place. TSO augments the facilities already available with 
the operating system: batch processing, teleprocessing, and other data processing activities can take 
place concurrently on the same system. 


Once an installation has generated a system that includes TSO, time sharing operations can be 
started and stopped at any time by the system console operator. The operator can specify how many 
regions of main storage are to be assigned to time sharing users. Each region can serve many users, 
whose programs are swapped back and forth between main and auxiliary storage. Time sharing, or 
foreground operations, can take place concurrently with batch or background operations. 
(Background jobs are not swapped.) If the user chooses, he can dedicate his system to time sharing 
and run only foreground jobs. If there are periods when TSO is not needed in the system, time 
sharing operations can be stopped, and the system will then process background jobs in the usual 
way with MVT and TCAM. 


Terminal communications are handled by the Telecommunications Access Method (TCAM) 
through an interface that allows the use of standard sequential access method I/O statements and 
macro instructions. 


All of the MVT facilities are available to a background job. Foreground jobs can use most of the 
operating system access methods for data set access (e.g., BSAM, QSAM, BDAM, etc.). All devices 
available to these access methods are usable by foreground jobs. A detailed list of restrictions is in 
the “Restrictions and Limitations” section of this manual. 


Execution of Background Jobs from the Terminal 


In addition to the foreground execution of programs, TSO allows jobs to be submitted for execution 
in the background, or batch, portion of the system. If his installation authorizes it, a user can submit 
a background job at his terminal, be notified of the job’s status, and then receive results of the job 
at the terminal. If he chooses, he can specify that the output of his job be produced at the 
computing center, rather than at the terminal. 


Foreground-Background Compatibility 


Because time sharing is carried out within the framework of MVT job and task management, the 
foreground and background environments are compatible. TSO uses the same data formats, 
programming conventions, and access methods as the rest of the operating system. The programming 
languages and service programs available with TSO are compatible with their background 
counterparts. 


The TSO command language is also generally compatible with the Conversational Remote Job 
Entry (CRJE) command language. Programs can be developed in the foreground and stored in 
background libraries. These programs are compatible with other system programs. Most problem 
programs can be executed in either the background or the foreground without revision or 
recompilation. 
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Restrictions and Limitations 


Certain facilities are unavailable to foreground jobs, although they remain available to background 
jobs. These include: 


¢ The BTAM and QTAM telecommunications access methods. 
¢ The Graphics Access Method (GAM). 
e The EXCP equivalents of the BTAM, QTAM, and GAM access methods. 


e Main storage requests for hierarchy 1. (All foreground requests for main storage are allocated to 
hierarchy 0.) 


¢ Use of Job Control Language in the foreground for other than single-step jobs. (The TSO 
command language is used to provide the equivalent of multi-step jobs.) 


« Checkpoint/Restart Facility. (Foreground requests for checkpoint are ignored.) 
« Rollout/Rollin Option. 
e TESTRAN Facility. 


¢ Multivolume and tape data sets are not supported by most Command Processors and cannot be 
allocated dynamically. 


SVC numbers 92 through 102 (decimal) are added to the system for TSO. The following SVCs 
can be issued by problem programs in the foreground region: 


e SVC 93--TGET/TPUT (execute terminal I/O). 

e SVC 94--STCC (specify terminal control characteristics). 

e SVC 95--TSEVENT (notify the supervisor of an event). 

e SVC 96--STAX (specify a terminal attention exit). 

« SVC 97--Breakpoint (used by TEST command). 

e SVC 98--PROTECT (protect a data set with a password). 

e SVC 99--Dynamic Allocation (of a data set). 

¢ SVC 100--Submit a job to the background. 

e SVC 102--AQCTL -- used by TCAM to communicate with problem programs. 


Of these, only SVC 98--PROTECT--can be issued by programs executing in the background. 
SVCs 92 (TCB EXCP) and 101 (TCAM-TSO Communication) are used only by supervisor 
programs. 


Including TSO in a system adds no restrictions to programs executed in the background. For 
example, other teleprocessing applications can be run simultaneously. 


System Control 


The management of an installation can shift most of the responsibility for controlling the time 
sharing system from the operator at the system console to users at remote terminals, called control 
terminals. A control terminal user can alter the system configuration to meet changing work loads. 
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For instance, he can assign an extra region during peak periods, and then release it to be used for 
batch operations during slack periods. Such changes require no shutdown of TSO and are not 
noticed by the users of other regions. Even the starting and stopping of TSO operations are 
accomplished without shutting down the system or affecting background operations. 


Job Definition and Scheduling 


To the operating system, each terminal session from LOGON to LOGOFF is one terminal job, 
corresponding to a single step batch job. The job control statements that define a terminal job are 
stored in the LOGON procedure used to begin the session. The “EXEC” JCL statement in the 
LOGON procedure identifies the program the user wants loaded into his region for execution. The 
program may be the TSO-provided command language handler or an installation provided 
application program. 


An important feature of TSO is the dynamic allocation of data sets for time sharing users. A user 
may defer definition of his data sets until he requires them. During LOGON processing, any data 
sets named on Data Definition (DD) statements in the procedure are allocated to the terminal job. 
Any data sets requiring volume mounting by the operator, must be defined here. The procedure also 
includes dynamic DD statements (similar to a DD DUMMY), which reserve control block space for 
data sets the user may allocate during the session. The dynamic allocation facility allows data sets to 
be created, deleted, concatenated, or separated without previous allocation at the beginning of the 
job step. 


Tuning the Time Sharing System 


In a time sharing system, execution time is divided among the active foreground jobs and 
background jobs in brief time slices. A time slice must be long enough to perform a meaningful 
amount of processing, but not so long that the time between successive slices prevents quick 
response to conversational users. At the same time, time slices cannot be so short and frequent that 
system overhead for swapping and task switching becomes excessive. Balancing these factors 
depends on the number and type of jobs the system is processing. A solution for one job mix is not 
necessarily suitable for another job mix. The TSO time sharing algorithms -- the formulas used to 
calculate the division of time among jobs -- are based on several variables, most of which can be 
specified by the installation to tune the system for their particular workload. Some of the tuning 
variables such as the number of foreground regions and the maximum number of users, can be set 
or modified by the system operator or a user at a control terminal whenever the system is running. 
Others are specified as parameters in SYS1.PARMLIB. These parameters are used when the 
operator starts the time sharing operations. 


The time sharing algorithms are described in detail in the ‘System Summary” section of this 
manual. They are implemented by a subroutine called Time Sharing Driver. The Driver makes 
decisions about system functions such as swapping and task switching. An installation may 
experiment with other time sharing algorithms by modifying or replacing the driver, and specifying 
use of the new Driver in the SYS1.PARMLIB parameters used when the operator starts time sharing 
operations. 


Execution time may also be affected by the choice of modules to be included in the Link Pack 
Area (LPA) extension in the Time Sharing Control Task (TSC) region. The size of the LPA 
extension and the amount of main storage dynamically allocated by the driver are major factors in 
determining the size of the TSC region. The installation may let the TSC calculate its own region 
size or may specify a TSC region size, either in SYS1.PARMLIB or on the START command used 
to start TSO, to compensate for additional main storage requirements created during tuning. 
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Monitoring System Use and Performance 


By extending the services of the system to many concurrent users, TSO makes the operating system 
more useful to more people. However, installation management’s job of monitoring system use and 
performance becomes more complex. Three tools are provided to help management maintain a clear 
picture of what the system is doing. 


System Management Facilities (SMF): The SMF option can be used with TSO. Both the data 
collection and dynamic control facilities are extended to the foreground environment. 


With the data collection facility, records describing both the system environment and individual 
user activity are written to the SMF data sets in a format similar to that used for background 
records. The system environment data includes: 


e Machine configuration. 
e Resource status. 
e« Library management information. 


This information is recorded whenever time-sharing operations are started, modified, or stopped by 
an operator. The user data includes: 


¢ I/O device use. 

e Data set use. 

e Main storage used. 

e Time resident in main storage. 
¢ Time actually spent executing. 


The user data is recorded at LOGON and LOGOFF and during a terminal session whenever a user 
changes the status of his data sets with the dynamic allocation facility. The information on the use 
of data sets is particularly useful to the installation for controlling the use of secondary storage in 
the time-sharing environment. 


The SMF dynamic control exits give the installation access to control program information at key 
points during the processing of jobs, including foreground jobs. The step initiation and termination 
exits are taken, if present, when a user begins or ends a terminal session. These routines can record 
information and control processing for foreground jobs just as they do for background jobs. SMF is 
discussed in detail in the publication IBM System/360 Operating System: System Management Facilities, 
GC28-6712. 


An additional installation exit, separate from the SMF dynamic control exits, is provided from the 
routine handling user LOGON. This exit allows the installation to establish its own user verification 
and control procedures, independent of those supplied with the system. The section of this 
publication “Writing a Logon Pre-prompt Installation Exit’ describes the parameters passed and what 
actions the exit may take. 


MONITOR Command: The MONITOR command allows the operator to watch the changing 
workload on the system over a period of time. In addition to the job initiation, data set, and volume 
information formerly available with the DISPLAY command, he can request notification of 
time-sharing users logging on and off the system. The DISPLAY command now gives the system 
workload at a particular point in time, and has been extended to include information relative to the 
time-sharing environment, such as the number of foreground regions and the number of active 
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terminals. Both MONITOR and DISPLAY, like other operator commands concerned with the 
time-sharing operation, are available to a control user at a remote terminal as well as the system 
operator at the console. 


TSO Trace Program: The TSO Trace Writer Program provides a detailed history of what the system 
does over a period of time. The Trace Program records a stream of information that all components 
of the system are continuously passing to the Time Sharing Driver. The Driver uses this information 
in its calculations of resource allocation. When the operator starts the Trace Program, it intercepts 
these event signals and records then with a time stamp in a data set. Typical events recorded are 
‘“‘iob requesting terminal input” and “swap completed.” The TSO Trace Data Set Processor can be 
used at a later time to format and print out the information recorded by the Trace Program. The 
Trace Data Set Processor can be requested to list only those events associated with a particular 
component of the system, such as the dispatcher, or to list only those events associated with a 
particular terminal or set of terminals. Using this information, system management can determine 
how well the system is responding to the workload and make adjustments to the tuning variables if 
necessary. 


System Security 


The need for adequate data and program protection is increased in the time-sharing environment, 
where many persons are simultaneously using the system. The system itself must be protected 
against unauthorized users. Each user’s programs and data must be protected against accidental 
destruction by other users. Confidential data must be safeguarded against unauthorized access. 


User Verification 


Any user starting a terminal session is required to supply a user identification recognized by the 
system; that is, one that has been defined by the system administrator. The installation may also 
require the user to supply a unique and confidential password with the LOGON command. 


Further verification of a user’s identity can be performed by the optional installation routine 
called when a user logs on. This routine can request further information from the applicant and 
deny him access to the system if he fails to provide it. 


Program Protection 


Although a number of users may have jobs assigned to the same foreground main storage region, 
only one user’s job is present in the region at a particular time -- the other jobs are temporarily 
stored in the swap data sets. No user can accidentally destroy or tamper with another user’s job. 
Like the background regions under MVT, the foreground regions have unique storage keys, 
preventing a job from modifying any area of main storage outside its assigned region. 


Data Set Security 


Because any user can refer to any data set in the system catalog, the data set security facility of the 
operating system is extended to allow individual users to protect their own data sets from 
unauthorized reference. A user can assign one or more passwords to a data set. If anyone 
subsequently attempts to open the data set, he is prompted for the password(s). If he fails to supply 
the correct password in two attempts, his program is terminated. 


The password assigned to a data set can be the one associated with the user for LOGON. In this 
case, the user will not be prompted for the password when opening his own data set. Any other 
user, however, must supply the correct password to refer to that data set. 


Passwords can be assigned for two levels of protection: 
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¢« Modification protection. No password is required to open the data set for reading, but a password 
must be supplied to write into the data set, or to delete it. This type of protection is required for 
system libraries and data sets, to prevent accidental modification or to prevent a user from 
assigning a password and locking out all other users. There is no performance degradation in 
opening the data sets for reading. 


¢ Read protection. The password must be supplied to open the data set for reading. 


Authorizations 


Special authorizations in the User Attribute Data Set are required for the use of some TSO facilities. 
Specific authorization is required for: 


e Submission of jobs for execution in the background. 
¢ Use of system operator commands from the terminal. 
¢ Use of commands to modify the User Attribute Data Set itself. 


The User Attributes Data Set should be password-protected, to prevent assignment of these 
authorizations by anyone other than the system administrator or his designate. 


Capabilities of the TSO Command Language 


The TSO command language serves two separate, but related, purposes: 


e It gives the terminal user a simple means to request the system to perform work. 
e It gives system personnel a framework for applications. 


Functions available through the commands supplied with the system include: 


e Data set management. 
¢ Program development. 
e Program execution. 
¢ System control. 

The following sections describe these capabilities and are followed by a description of the 
applications available as IBM Program Products. Installation management has complete control over 
which functions are available to each terminal user. 


Data Set Management: The TSO command language includes commands to enter, store, edit, and 
retrieve data sets consisting of text, data, or source programs. Essentially, the commands give the 
terminal user the data set management functions of the operating system. Through the use of default 
values and data set naming conventions, the commands can be simple enough for the 
non-sophisticated user. 


Data from the terminal goes into standard operating system sequential or partitioned data sets. 
Conventions for immediate correction of keying errors are available for each terminal device type. 
At a 2741 Communications Terminal, for instance, the user can just backspace over an error and 
type in the correct characters. 


At the user’s option, the system will assign a number to each line of data as it is entered. Later, 
the user can retrieve and edit the line by referring to this line number. The user can also retrieve a 
line by specifying a string of characters contained in the line, and having the system scan the data 
set for it. 


Program Development: TSO offers convenient facilities for program development. The programmer 
can use the data-handling facilities to create source programs and to have them syntax-checked 
line-by-line as he enters them. Any operating system language processor can be invoked from the 


20 TSO Guide (Release 21.7) 


terminal. Some language facilities and translators designed especially for the terminal environment 
are discussed under “IBM Program Products.” 


Compiler diagnostic messages and listings can be directed to the terminal, allowing the 
programmer to correct errors immediately and recompile the program. Once the program compiles 
successfully, it can be tested conversationally. The programmer can start and stop execution from 
the terminal, inspect and modify main storage and register contents, trace and control the program 
flow. 


Because of background-foreground compatibility, programs produced at the terminal can be 
executed in either environment. Programs in the foreground can use the sequential access methods 
(BSAM and QSAM) to direct I/O to the terminal. In the background, the same unmodified 
programs can address a data set or unit record device. 


Program Execution: Programs can be invoked at the terminal in several ways. Any load module can 
be established as a command and executed simply by keying in the program name at the terminal. 
Load modules not defined as commands can be invoked in the foreground with the CALL 
command. If a program uses data sets, a command procedure can be used to allocate them. Entering 
the one-word procedure name can allocate the data sets, invoke and start the program, and free the 
data sets again on program termination. Whenever a program in the foreground terminates with an 
error condition, the testing facilities can be used to determine the nature of the error. 


The terminal user can also submit jobs to the background job stream. Commands similar to those 
used for the Conversational Remote Job Entry (CRJE) facility are used to create job control 
language describing the job, and to submit it to the batch job stream. The user can request 
notification of job completion at his terminal, and can have job output directed either to his terminal 
or to a device at the computer site. 


System Control: Certain users can be authorized to use commands for controlling system operation. 
With the proper authorization, a user at a remote terminal can use standard operator commands 
such as DISPLAY and MODIFY to control the time-sharing portion of the system. 


A separate control facility (ACCOUNT) allows an authorized terminal user to establish and 
maintain the profile of each system user. Using special commands from his terminal, he can define 
or modify user passwords, account numbers, and procedure names, and control authorizations and 
restrictions for each user. 


IBM Program Products 


The command language is designed so that new commands and applications can be easily integrated 
into it. Applications available from IBM as Program Products look the same as other commands to 
terminal! users. 


The IBM Program Products available for TSO systems are introduced briefly in the following 
paragraphs. Each is discussed more fully in later chapters of this manual. The Bibliography lists a 
source of further information about the Program Products. 


Problem Solving 


Three language processors specially designed for mathematical problem solving by users who are not 
necessarily professional programmers are available. Two are part of the Interactive Terminal Facility 
(ITF). The third is Code and Go FORTRAN, which is discussed with the other FORTRAN 
Program Products in the next section. 
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ITF: BASIC is a simple, algebra-like language easily learned by anyone familiar with mathematical 
notation. 


ITF: PL/I is a subset of full PL/I that provides a powerful conversational language that is easy to 
learn and use. ITF: PL/I can be executed line-by-line as it is entered, or collected into procedures 
and subroutines for later execution. Errors in either ITF: BASIC or ITF: PL/I can be detected as 
soon as the statement is entered and can be corrected immediately. 


Programming 


Program Products to aid the users of several programming languages are available with TSO. There 
are four types of products: 


« Compilers. 

e Libraries to support the compilers and object programs. 
e Prompters. 

e Interactive debug programs. 


The compilers can be used in either background or foreground environments. In the foreground, 
they provide diagnostics and listings formatted for the terminal. For instance, diagnostic messages 
can optionally refer to source errors by the line number assigned by the EDIT command. With the 
line number, the user can retrieve and correct the statement without having a complete listing 
displayed at the terminal. 


Prompters are initialization routines that allow the user to invoke a compiler with a single 
command, such as FORT or RUN. The prompter handles all data set allocations and sets processor 
options. If the user omits necessary information, such as the name of the source program to be 
processed, the prompter requests the information with a terminal message. 


Interactive debug programs provide execution-time program testing and debugging functions. 
Using commands, the user can cause the Interactive Debug to establish, remove, and list 
breakpoints; display and change data values; alter or trace flow of program execution; display the 
source program; monitor user-specified conditions; and execute prespecified subcommands at 
breakpoints. 


The following paragraphs introduce the Program Products available for each programming 
language. The chapter “Programming at the Terminal” discusses these products in greater detail and 
shows how other operating system processors can be used from the terminal. 


FORTRAN: There are five Program Products for FORTRAN programmers: two language 


| processors, a library for use with either processor, a prompter, and an interactive debug program: 


Code and Go FORTRAN, FORTRAN IV (G1), the FORTRAN IV Library (Mod J), the TSO 


| FORTRAN Prompter, and FORTRAN Interactive Debug. 


COBOL: Two language processors, a prompter, and an interactive debug program are available for 
COBOL programmers: the Full American National Standard COBOL Version 3 or 4 compiler, the 
TSO COBOL Prompter, and COBOL Interactive Debug. 


PL/I: Two language processors and two supporting libraries are available for PL/I programmers: 
the PL/I Optimizing Compiler, the OS PL/I Checkout Compiler, and the PL/I Resident Library 
and the PL/I Transient Library. The compilers incorporate a prompting routine. 


Assembler Language: The TSO Assembler Prompter is available to invoke the Assembler (F). The 
Assembler (F) is not a Program Product. 
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Text and Data Handling 


The TSO Data Utilities Program Product provides four commands (COPY, LIST, MERGE, and 
FORMAT) to manipulate data sets and to format text for output at the terminal or on a high-speed 


printer. 
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Command Language Facilities 


TSO terminal users define their work in the TSO command language. A command can be thought of 
as a request from the terminal user for the system to perform a particular function. This chapter 
describes and gives examples of the facilities available through the command language. There are 
commands for elementary functions such as entering, editing, and retrieving data; remote job entry; 
mathematical calculation; and program development and testing in several programming languages. 
These important functions are the base on which the installation’s own terminal-oriented 
applications and systems are developed. 


Conventions at the Terminal 


The command is the means by which work is defined at the terminal. The first word of a command 
is always the command name. It is used by the system to select a command processor (a problem 
program) from the system command library or a user command library. Any further information in 
the input line, the command operands, is passed to the command processor in a parameter list. 
Operands are separated, or delimited, by either blank spaces or commas. A few commands require 
that groups of related operands be enclosed in parentheses. 


Most operands are optional. If an optional operand is not entered with the command, the system 
assumes the default values and proceeds as if the user had entered that value. If the missing operand 
is not one that can be defaulted, for instance, a data set name, the system prompts the user for it 
with a message such as “ENTER DATA SET NAME”. When all the operands have been either entered or 
defaulted, the command processor proceeds to perform the desired function. Some of the command 
processors, such as EDIT, accept, interpret, and perform subcommands, which follow the same 
syntactic rules as the general commands. 


Logging On 


To establish a connection with the system, the user activates his terminal, dials the computer, if 
necessary, and enters the LOGON command. He must always supply his user identification as an 
operand of the LOGON command; if he does not supply it, a prompting message is issued. Up to 
three additional levels of identification may be needed, depending on the accounting methods and 
security procedures used by his installation. 


The installation may require users to enter a password with the LOGON command. Each user can 
have one or more passwords associated with his identification. At terminals equipped with the print 
inhibit feature, the system is able to suppress printing of the password as it is keyed in. 


Associated with each password are one or more account numbers, and with each account number, 
one or more LOGON Procedure names. The LOGON Procedure contains the Job Control 
Language statements defining the user’s terminal job, just as cataloged procedures define 
background jobs. For instance, the LOGON Procedure may allocate certain commonly used data 
sets. Whenever there is only one account number or procedure name, the system selects it by 
default, and the user is not required to enter it. 


The system acknowledges that the LOGON has been accepted when it has checked the 
identification supplied and has determined that the resources requested in the LOGON Procedure 
are available, and the user can begin his work. 
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Input Editing 


Some system editing is provided for every line of input from the terminal. Lowercase alphabetic 
characters (from terminals that have them) are translated to uppercase, except for certain 
text-handling applications. Each user can define his own character-delete and line-delete characters 
for correcting any keying errors in input lines. There are default character-delete and line-delete 
characters for the typewriter-like terminals (the cursor controls can be used on the 2260 and 2265 
Display Stations). If a user defines the quotation mark as his character-delete character, and percent 
sign as his line-delete character, then enters the line: 


etoain%aBCc"deee 
it is received by the system as 
ABCDE 


Users whose terminals have backspace and attention keys may define those keys as their 
character-delete and line-delete characters. 


Entry Modes 


Immediately after LOGON, the system is ready to accept any command in the command libraries. 
The terminal is said to be in command mode. Some commands place the terminal in other entry 
modes: EDIT, for instance, has an input mode, that accepts successive lines of input for a data set; 
and an edit mode, that accepts EDIT subcommands. Other commands, such as TEST, ACCOUNT, 
OUTPUT, and OPERATOR also define special purpose modes. 


The Attention Key 


The attention key can be used to transfer from one mode to another, or to interrupt a program or 
command processor during execution. Any command in process can be cancelled by hitting the 
attention key and entering a new command. A user program can be interrupted with the attention 
key to transfer to the test mode for debugging activity, then the program can be restarted. 


Assembler language user programs can define attention exit routines with the STAX macro 
instruction. Control will be passed to such a routine when an attention is entered. 


An important function of the attention feature is to prevent the user from being “‘locked out” of 
the system while a long-running program executes, or while voluminous output is displayed at the 
terminal. For terminals without attention keys, the attention feature can be simulated. The user can 
specify a string of characters, such as “STP”’. that is to be interpreted as an attention. The system 
can be instructed to interrupt any long-running program or terminal output periodically to accept 
either the simulated attention character string, or a digit to specify the level of attention exit or a 
null line to continue processing. 


Data Set Naming Conventions 


Unless requested not to, the system appends two qualifiers to a simple data set name specified by a 
user: a descriptive qualifier and user identification qualifier. The user identification qualifier is. the 
same as the user identification specified with the LOGON command and is appended as the 
left-most qualifier of data set names that follow the TSO naming conventions. The user never needs 
to enter his identification qualifier; it is always known to the system. 


The descriptive qualifier is placed at the right of the user entered data set name. It tells the 
system what kind of data is recorded in the data set and for what purposes it can used. For 
instance, the qualifier for a data set containing COBOL source statements is COBOL; for a load 
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module, LOAD. Whenever possible, the system determines the appropriate descriptive qualifier from 
the command referring to the data set, and the user need not enter it as part of the name. In some 
cases, the user must supply it, as part of the data set name entered with the command, or in 
response to a prompting message. 


To refer to a data set that does not follow the naming conventions, or that has an identification 
qualifier different from the one specified at LOGON, the user encloses the fully qualified data set 
name in apostrophes. The system does not append any additional qualifiers in this case, and uses the 
name ‘‘as is,” except for translation to uppercase, to search the catalog. Using this technique, several 
users may refer to a data set with the shared attribute at the same time. 


Data Entry 


The EDIT command is used to enter information into the system. Because almost every system 
application will use some of the editing facilities, an overview of the command is presented here. 
Later sections will demonstrate some of the particular uses of the command. 


Creating Data Sets 


The EDIT command processor creates or modifies data sets with sequential organization, including 
members of partitioned data sets. The data sets contain only printable characters in EBCDIC 
representation. A data set name is entered with the EDIT command. If the user specifies the data 
set is old, EDIT opens it for modifications. If it is a new data set, EDIT invokes the dynamic 
allocation routines to create it. The data set attributes, such as blocksize and record length, can be 
specified by the user, or defaulted to standard values. For data sets containing source-language 
programs, the standard attributes are determined by the compiler to be used. 


One input line from the terminal normally becomes one record in the data set. Because of this 
equivalency between records and lines at the terminal, data sets created by EDIT are called line data 
sets. On request, EDIT associates a line number with each record of the data set as it is entered. 


Entry Modes for EDIT 


Depending on the type of work the user is doing with his data set, he uses one of two entry modes 
provided by EDIT (some other modes specifically for particular programming languages are 
discussed later). The input mode allows rapid entry of successive lines of input for the data set. The 
edit mode allows subcommands to be entered to modify, insert, or delete lines. 


Input Mode 


In input mode, the user enters successive lines of input. The lines are normally appended at the end 
of the data set, although the user can request they be inserted at some other point. The only 
subcommand recognized in the input mode is the null line (hitting the return key with no preceding 
characters), which requests transfer to the edit mode. 


Services available in the input mode include translation of lowercase letters to uppercase, 
translation of tab characters to a series of blanks, and interpretation of the character-delete and 
line-delete characters. If line numbers are being assigned to each line, the user may request each 
new number be typed out by the system at the beginning of each input line. If line numbers are not 
being assigned, the user can request prompting for each new line by an underscore. If no prompting 
is requested, lines are entered one after another, with no intervening response from the system. 
Programming language syntax checkers can be requested to process input lines as they are entered. 
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Edit Mode 


In edit mode, the user enters subcommands to point to particular records of the data set, to modify 
or renumber records, to add and delete records, to control editing of input, or to compile and 
execute a program. 


Whenever the terminal is in edit mode, the user is considered to be positioned at a particular 
record, or line, of the data set. The EDIT command processor maintains a current line pointer to 
keep track of the user’s position. In general, the current line pointer, which can be referred to in 
subcommands by an asterisk (*), is positioned at the last line referred to, entered, changed, or 
printed. Using the subcommands provided, the user can move the current line pointer to any record 
in the data set. 


For line-numbered data sets, specifying a line number as an operand of a subcommand moves the 
pointer to that record before the action requested by the subcommand is carried out. This method 
of operation is called line number editing. 


Another method of repositioning the current line pointer is called context editing. A set of 
subcommands is provided to reposition the current line pointer without reference to line numbers. 
The user can move the pointer up or down a specified number of lines, or request the system to 
find a line with a particular series of characters in it, and move the pointer to it. 


Modifying Data Sets 


The most common use of the EDIT command for existing data sets is the addition, deletion, or 
modification of records. The INSERT and DELETE subcommands handle single or multiple record 
insertions and deletions. The CHANGE subcommand allows the user to replace one character string 
with another, not necessarily of the same length. 


Data Set Management Commands 


To allow the user to manage his data stored on auxiliary storage devices, a set of data set utility 
commands is included in the TSO command language. All user data is kept in standard operating 
system data set, and as a default, data sets used by foreground programs are entered in the system 
catalog, reducing the amount of information the user must supply about the data set from the 
terminal when he refers to it. 


The LISTCAT and LISTDS commands retrieve information from the system catalog for the user. 
He can find out what data sets are currently allocated to him, and what the attributes of the data 
sets are. The RENAME command can assign a new data set name to an existing data set, or add an 
alias name to a partitioned data set member. The DELETE command removes a data set from the 
catalog, and frees the auxiliary storage space it occupies. 


The PROTECT command is the facility to assign password protection to data sets. Protection can 
be assigned for read access and for write and delete access. Multiple passwords can be assigned to a 
single data set. 


The ALLOCATE and FREE commands invoke the dynamic data set allocation routines from the 
terminal. A user who wants to run a program that requires one or more data sets not currently 
allocated to his foreground job enters ALLOCATE commands to have the data sets assigned. The 
FREE command is used to release the data sets assigned by ALLOCATE. The ALLOCATE 
command can also be used to find data sets not in the system catalog, and to control the size of 
new data sets and the volumes to which they are assigned. 
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The ATTRIB command can be used to build a list of data set attributes. These attributes are 
specified by the operands of the command. The operands are similar to the DCB parameters of the 
JCL DD statement. The attributes in an attribute list can be assigned to data sets being allocated by 
the ALLOCATE command. 


TSO Data Utilities 


The TSO Data Utilities Program Product is available to augment the data entry and data set 
management commands by providing a text-formatting capability and data set utilities for terminal 
users. The product provides four commands: 


« FORMAT, to format textual information into pages. 

e« LIST, to display all or part of a data set at the terminal. 

« COPY, to copy a data set. 

« MERGE, to merge all or part of one data set into another. 


The FORMAT and MERGE commands can also be used as subcommands of EDIT (EDIT 
incorporates a less powerful listing capability). The COPY and MERGE commands can be used for 
access to ASCII tape data sets. See the publication IBM System/360 Operating System: Planning for 
the Use of Information Interchange Standards, GC28-6756, for details. 


Text-Handling 


The EDIT, FORMAT, and LIST commands provide a facility for the entry, editing, storage, and 
output of text. With the EDIT command, the terminal user creates a data set with the type qualifier 
TEXT, and enters the material line-by-line. If his terminal has both uppercase and lowercase letters, 
the material will not be translated to uppercase letters, but will be saved just as entered. The user 
can specify what tab settings he wants to use, and the system will convert tabs in the material into 
strings of blanks of the proper length. The use of line numbers is optional. 


The user formats the data set by inserting format control records into it. A format control record 
is entered as a separate line in the data set, starting with a period in the first position, followed by a 
control word (or a two-character abbreviation). The EDIT processor does not interpret the controls; 
they are retained in the data set for interpretation later by the FORMAT processor. The controls 
allow the user to: 


« Print a heading on each page. 

« Center lines of text between margins. 

¢« Control the amount of space for all four margins on the page. 
e Control line spacing. 

e Justify left and mght margins of the text. 

e Number pages of output consecutively. 

¢ Halt printing when desired. 

« Print multiple copies of selected pages. 


The FORMAT processor scans the data set for the format controls and inserts blanks, carrier 
return characters, headings, and page numbers as needed. At the user’s option, the output can be 
formatted for a terminal or saved in a data set for deferred printing, either on the terminal (with the 
LIST command) or on a high-speed printer. Either an all-capitals or an uppercase and lowercase 
print chain can be used on the printer. 
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Data Set Manipulation 


The COPY, LIST, and MERGE commands allow the terminal user to move information between 
data sets and to display sets at the terminal. 


The COPY command will duplicate sequential or partitioned data sets or a member of a 
partitioned data set. While doing so, it can resequence or change the record length, blocksize, or 
record format as requested. The MERGE command will copy all or part of one data set or member 
into another data set and will resequence the record numbers in the receiving data set if requested. 
Both these data commands will process tape data sets in ASCII format. Tape devices must be 
allocated to a user in his LOGON procedure. 


The LIST command displays all or part of a data set at the terminal. The user can request that 
fields within records be rearranged for output, and line numbers can be suppressed or included. 


Compiling and Executing Programs 


A variety of commands are provided to give the user control over program compilation and 
execution. The form of the program determines command selection. For those language processors 
that are supported by a prompter Program Product or that incorporate a prompter, the terminal user 
requests a compilation of a source program with a single command. The prompter performs the 
following functions: 


e Requests any necessary operands with messages to the terminal. 

e Sets other compiler options to default values suitable for the terminal environment. 
e Dynamically allocates the data sets needed by the compiler. 

e Invokes the compiler. 


For instance, if an installation has the TSO COBOL Prompter and the Full American National 
Standard COBOL Version 3 or 4 processor Program Products, the user can enter the COBOL 
command to compile his program and produce an object module. The LOADGO command can then 
be used to call the OS Loader to bring the program into main storage for execution, or the LINK 
command can be used to call the Linkage Editor to create a permanent load module. 


During program development, when a programmer is repeatedly compiling and testing a program, 
he can use the RUN command to invoke it. RUN first calls the appropriate prompter and compiler, 
and then the OS Loader (except when used with the PL/I Checkout Compiler, which provides its 
own execution facilities). In any case, RUN provides a compile-load-go sequence with a single 
command. RUN can be used as a command, or as a subcommand of EDIT. Figure 1 is a summary 
of the commands for executing programs. 
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Figure 1. Program Control Commands 
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Any load module, including language processors for which there are no prompters, can be 
invoked with the CALL command. For instance, the FORT command provided by the TSO 
FORTRAN Prompter Program Product invokes the FORTRAN IV (G1) compiler. If a programmer 
wants to use the FORTRAN IV (H) processor for a particular compilation, he can enter the 
command: 


CALL 'SYS1.LINKLIB( IFEAAB)' 'MAP,OPT=1' 


The compiler is loaded into the foreground region and given control. The options are passed to it as 
though they had been specified in the PARM field of an EXEC statement in Job Control Language. 
It is necessary for the user to allocate data sets for the compiler’s use before entering the CALL 
command. A series of ALLOCATE commands can be defined in a command procedure, so that 
they need not be entered every time a compiler is used. For more information about compiling and 
executing programs, refer to the TSO Terminal User’s Guide. 


The TEST command can also be used to invoke a user program, and to control its execution. 
Before passing control to the program, TEST allows the user to establish initial values to be passed 
to the program as test data, and to set up breakpoints where execution is to be interrupted for 
displays and other debugging activity. 


Breakpoints are established with the AT subcommand in test terminal mode. AT specifies a 
symbolic or absolute address in the program where execution is to be interrupted. The action to be 
taken at the point of interruption, such as listing or modifying storage and register contents, can be 
specified in a pre-stored string of TEST subcommands, or entered through the terminal at the time 
of interruption. Main storage contents can be displayed at the terminal or stored in a data set for 
deferred printing. TEST subcommands allow the programmer to load additional programs into 
storage, to delete or replace programs in storage, to issue GETMAIN and FREEMAIN as 
subcommands from the terminal, to define the location and attributes of symbols, and to start and 
stop program execution. 


Users of FORTRAN IV (G1) and Code and Go FORTRAN can use FORTRAN Interactive 
Debug for execution-time program checkout; similarly, users of Full ANS COBOL Version 4 can 
use COBOL Interactive Debug. 


Remote Job Entry 


The command language includes the SUBMIT, STATUS, OUTPUT and CANCEL commands to 
handle submission of jobs for execution in the background. These commands have the same format 
as the commands available with the Conversational Remote Job Entry (CRJE) facility of the 
operating system. 


To have a job executed in the background, the user places the job control statements defining the 
job in a data set. By convention the jobname is the one-to-seven character user identification, plus a 
single character to provide uniqueness. The user then enters a SUBMIT command, including the 
name of the data set as an operand. SUBMIT will generate a standard jobname and a JOB 
statement if one is not included in the job definition. One data set can contain more than one job 
definition. Any time after entering the SUBMIT command, the user can inquire about the status of 
the job. The STATUS command returns information such as whether the job is waiting for 
resources, is executing, or is completed. The job can be terminated with the CANCEL command. 


A new keyword has been defined for the JOB statement to allow automatic notification of the 
user when the job is completed. By coding NOTIFY= with his user identification, the user requests 
a message to his terminal when the job completes. The message is saved until he enters a LISTBC 
command. The OUTPUT command allows the user to display job output (SYSOUT) at his terminal, 
to save it in a data set, or to delete it. 
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System Control 


Two facilities are provided for the installation manager or system programmer to control operation 
of the system from his terminal. The ACCOUNT command adds, changes, or deletes entries in the 
User Attributes Data Set, which is the list of all authorized users of the system, together with the 
characteristics defining their profiles. The OPERATOR command places a terminal in a special 
mode allowing entry of commands normally available only at the system console. Use of either of 
these facilities requires special authorization. Users with such authorization are called control users. 


User Authorization 


When a control user enters an ACCOUNT command, his terminal is placed in account mode. With 
subcommands, the control user defines each user to the system, specifying his identification, 
passwords, account numbers, and LOGON Procedure names. This information is placed in the User 
Attribute Data Set, along with indications of any special authorizations the user may have, such as 
permission to use the ACCOUNT or Remote Job Entry facilities, and a limit on the region size he 
may request. This information will be retrieved whenever the user logs on, to verify his authority to 
use the system, and to define his foreground job. 


System Operation 


By entering the OPERATOR command, a control user has access to the system operator commands 
MODIFY, DISPLAY, MONITOR, CANCEL, and STOPMN. The commands have the same format 
and effect on the TSO system as if they were entered through the operator’s console, as specified in 
the publication IBM System/360 Operating System: Operator’s Reference, GC28-6691. 


Command Procedures 


A command procedure is a data set containing a list of TSO commands and subcommands. The data 
set name is entered as an operand of the EXEC command, and the commands are executed, 
one-by-one in the order in which they appear in the procedure. When one command or 
subcommand is completed, the next is read from the procedure and processed as though it had been 
entered from the terminal. The commands can be typed out at the terminal as they are executed, or 
the user can suppress the listing with an operand of the EXEC command. 


An installation can keep its command procedures in a partitioned data set called a command 
procedure library. Each member of the data set can contain one procedure. The installation defines 
its command procedure library in the SYSPROC DD statement of the logon procedure for terminal 
users. Each terminal user in the installation can define his own private version of the command 
procedure library by using the ALLOCATE command. 


The command procedure library must have been previously allocated to the file name "SYSPROC’ 
by step allocation at logon time or with the ALLOCATE command. 


The EXEC command can also be invoked implicitly if the procedure is a member of the 
command procedure library. The member name of the command procedure can be entered as a 
command name. When the name is not found in the command libraries, the system assumes it is in 
the command procedure library. 


Operand Substitution: Symbolic operands, starting with an ampersand ( & ), can be placed in 
commands and subcommands within command procedures. Values for these operands are supplied in 
the EXEC command invoking the procedure. A procedure (PROC) statement at the beginning of 
the procedure specifies how many positional operands will be supplied, and what keyword operands 
may be present. Default values for symbolic operands can be specified in the PROC statement. 
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Conditional Statements: The WHEN statement tests the return code from any command or program 
invoked during a procedure. A condition is stated with relational operators such as GT or LT 
(“greater than” or “less than’’). If the condition is satisfied, the command in the WHEN statement 
is executed. If it is not satisfied, the command following the WHEN statement is executed. The 
command in the WHEN statement can itself be an EXEC command, invoking another command 
procedure. 


Other Commands 


Several other commands are provided to allow the user to control the terminal environment and to 
aid him in using the command system. 


The TERMINAL and PROFILE commands are used to tailor the data entry conventions to the 
terminal type and user’s preference. TERMINAL allows him to specify the character string to be 
used to simulate an attention interruption if his terminal does not have an attention key, and to 
specify how often he is to be given an opportunity to simulate an interruption during long-running 
execution or output sequences. The PROFILE command is used to specify the character-delete and 
lme-delete characters, and other user options such as whether he wants prompting messages 
suppressed. 


The HELP command provides the user with reference information on command and subcommand 
syntax, function, and usage. For example, if a user has forgotten the function of the DELETE 
command, he can enter: 


help delete function 
The HELP command will return information explaining the function of the DELETE command: 


THE DELETE COMMAND IS USED TO DELETE A SEQUENTIAL DATA SET OR A MEMBER OF A 
PARTITIONED DATA SET. 


Requesting this information through the terminal is faster than searching for it in a printed manual. 


The SEND command is used to send a message to the system operator or to another user. The 
sender must know the user identifications of other users to whom he directs messages. Messages are 
displayed immediately at the receiver’s terminal unless the receiver has requested that messages be 
suppressed or unless he is not logged on. Messages not sent immediately are saved, and are 
transmitted if requested, when the addressee next logs on. 
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Programming at the Terminal 


The time sharing environment is especially well-suited to program development. The advantage of 
programming at a time sharing terminal is the reduction of job turn-around delays. The programmer 
can profitably devote himself to one project at a time -- he does not need other projects to work on 
while waiting for results from a batch computing facility. TSO provides services for terminal users at 
each step in program development: coding, compiling or assembling, testing, implementation, 
documentation, and program maintenance. 


Any compiler or assembler designed to run under the operating system can be invoked from a 
TSO terminal. Compilers can be executed in the foreground, or, via the SUBMIT command, in the 
background. Command language prompters are either incorporated in or separately available for 
several of the language processors. The TSO prompters, all IBM Program Products, provide specific 
commands to invoke the associated processors, and perform the following functions: 


e Request the user to enter necessary information such as the name of his source program. 
e Allocate data sets required by the processor and free them on completion. 


e Set any compiler options specified by the user and set default values for those options the user 
omits. 


| Prompters are available for Full American National Standard COBOL Version 3 or Version 4, 
FORTRAN IV (G1), and Assembler (F). Prompters are incorporated in the PL/I Optimizing 
Compiler, the OS PL/I Checkout Compiler, and the problem-solving language processors (ITF: 
BASIC, ITF: PL/I, and Code and Go FORTRAN). Each of the processors accepts a TERM option, 
a request for special formatting of diagnostics and listings for the terminal, and a NUM option, to 
control the use of EDIT line numbers in error messages. Syntax checking of source programs is 
provided for PL/I (F), FORTRAN IV levels (E), (G1), (G), and (H), and the problem-solving 
languages. The test mode gives the user real-time control over program execution for debugging. 
Similar facilities for ITF: PL/I, ITF: BASIC, Code and Go FORTRAN and the PL/I Checkout 
Compiler are discussed in the next chapter, ““Problem Solving.”’ 


Either the loader or the linkage editor can be invoked from the terminal. Users authorized to do 
so can add load modules to the system command library, where they will be available as commands 
to all system users. Any user can add programs to his own command library. Programs written in 
any language can be defined as command processors, but only assembler language has the facilities 
to make use of the command service routines such as input scanning and prompting. 


Because of foreground-background compatibility, production programs that will eventually be run 
in the background environment can be written and tested from the terminal. I/O that goes to the 
terminal in the foreground can be re-directed to a sequential data set in the background. No 
recompilation is necessary. 


The following sections describe the special terminal support provided for COBOL, FORTRAN, 
PL/I, and Assembler language programmers. Language processors for which no specific terminal 
support is provided can also be invoked in the foreground. (See ‘Other Compilers” in this chapter.) 


COBOL 


TSO provides the COBOL programmer with facilities for entering, compiling, and testing programs 
from his terminal. The programmer can use the COBOL command for compiling his program with 
the following IBM Program Products: 
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« TSO COBOL Prompter. 
e Full American National Standard COBOL Version 3 or Version 4 Compiler. 


The programmer can use the TESTCOB command to invoke the COBOL Interactive Debug for 
testing and monitoring programs compiled under the TEST option of the Version 4 compiler. 


Entering the Source Program 


The COBOL programmer uses the TSO EDIT command to create or modify his source program. 
With the EDIT command, he enters operands to name the data set containing the program, and 
identify it as an old program to be modified or a new program. 


With the terminal in input mode, the user enters successive lines of the program. The system 
accepts each line when he hits the return key of the terminal, and types out the line number of the 
next line. This line number becomes the sequence field of the COBOL statement in columns 1-6, 
and in addition is used in place of the compiler-generated ‘“‘card number” in program listings and 
diagnostic messages. Automatic line numbering can be suppressed, if desired, by an operand of the 
EDIT command. 


After the line number is typed out, the terminal is logically positioned at the continuation column 
(column 7) of the COBOL statement. The user can space or tab to Area A (column 8) or Area B 
(column 12) of the statement. These logical tab settings are automatically set by the EDIT program 
whenever a COBOL program is being processed. EDIT converts the tab characters to the necessary 
number of blanks to format the statement correctly. The number of blanks generated is independent 
of the physical tab settings at the terminal. The user can, if he wishes, override the standard settings 
by specifying his own with an EDIT subcommand. 


Compiling a COBOL Program 


The Full American National Standard COBOL Version 3 or 4 compiler is invoked with the COBOL 
command. The only required operand is the name of the data set containing the source program to 
be compiled. However, any of the compiler options (except DECK) can be entered with the 
command as operands. 


Three compiler options are available: TERM, PRINT/NOPRINT, and TEST/NOTEST (Version 
4 only). The TERM option orders the compiler to issue progress messages to the terminal as it 
processes the source program, for instance, “ANS COBOL IN PROGRESS,” and to issue diagnostic 
messages formatted for the terminal. An error or warning message directed to the terminal includes 
the line number of the source statement in error, and the compiler error message. Using edit mode 
subcommands, the programmer can retrieve the statement by line number, and correct the error. 


The PRINT/NOPRINT option, available only in the foreground, allows the programmer to 
choose whether the program listing is to be placed in a data set, displayed at the terminal, or 
suppressed. When developing a program from the terminal, it is not normally necessary to have the 
complete listing generated and displayed, since the error and diagnostic messages. are extracted and 
displayed through the TERM option. NOPRINT is the default value, and suppresses the listing. 
When source program errors have been corrected and the program is compiled a final time, the 
programmer specifies PRINT to generate the listing, which may be displayed at the terminal, or 
saved in a data set for deferred printing, either at the terminal or on a high-speed printer. The 
contents of the listing are controlled by the other options such as SOURCE, PMAP, and XREF. 


The TEST/NOTEST option allows the programmer to compile the program with support for later 
execution under control of COBOL Interactive Debug (TEST). A program compiled with the TEST 
option can be executed without COBOL Interactive Debug.) The TESTCOB command invokes 
COBOL Interactive Debug. 
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Program Execution 


The object program created by the COBOL compiler can be invoked with the LOADGO command, 
which calls the Loader to bring the program into main storage and pass control to it. The user 
enters ALLOCATE commands for any data sets needed by the program before invoking it. 


The object program can also be defined as, or as part of, a load module with the LINK 
command. As a load module, the program can be placed in a private or system program library. To 
define the program QUERY as a command in a private command library 
CONRAD.COMMANDS.LOAD, the LINK command is: 


LINK QUERY.OBJ LOAD( COMMANDS( QUERY )) COBLIB 


Once part of a command library, and once the private command library is concatenated to the 
command library (and linkage library), the program is invoked simply by entering the program name 
(or an alias) as a command. To invoke the program defined above, the user would type: 


QUERY 


The RUN subcommand of EDIT functions as a combination of the COBOL and LOADGO 
commands. It is especially useful during the testing phase of program development, since it can be 
used without leaving the edit mode. When a source program is complete, the user enters the RUN 
command, invoking first the compiler, then his object program. Whenever he detects and error 
requiring a change to the program, the programmer can immediately update his source program with 
EDIT subcommands, and enter another RUN subcommand. 


Interactive Programs 


COBOL programs can be designed to interact with a terminal user simply by defining the terminal 
as a file. Programs can read input lines from the terminal, act on the information, and respond. 
Because the terminal is defined as a sequential utility file, the same program can be executed in the 
background, reading and writing to sequential data sets or devices, without recompilation. 


To define the terminal as a file, the user enters ALLOCATE commands for the external names 
used in the name field of the ASSIGN clauses in the program. 


For programs containing ACCEPT and DISPLAY clauses, or which generate TRACE and 
EXHIBIT output for debugging, the SYSIN and SYSOUT files can be defined as the terminal. 
DISPLAY output is sent to the terminal instead of system output. TRACE and EXHIBIT output is 
also sent to the terminal. 


FORTRAN 


Two versions of FORTRAN IV with special support for the foreground environment are available as 
Program Products to TSO users: 


e Code and Go FORTRAN. 
e FORTRAN IV (G1). 


Both processors can also be used in the background environment. Three additional Program 
Products are available to complement the processors: 


e FORTRAN IV Library (Mod I), for use with either processor to provide list-directed 
input/output support, ASCII data set handling, and PAUSE and STOP output to the terminal. 
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e TSO FORTRAN Prompter, which allows the terminal user to invoke the FORTRAN IV (G1) 
processor with the FORT or RUN commands. 


e FORTRAN Interactive Debug, which allows the terminal user to test and debug his FORTRAN 
IV (G1) or Code and Go FORTRAN program at execution time. 


A FORTRAN programmer can also invoke the FORTRAN (E), (G), or (H) processors with the 
CALL command, but not with the RUN or FORT commands. The user is responsible for allocating 
the data sets needed by these compilers, and for specifying the compiler options. The prompter 
performs these services for the FORTRAN IV (G1) compiler, which also has output specially 
formatted for the terminal. 


Code and Go FORTRAN is optimized for a fast compile-and-execute sequence, carried out entirely 
within main storage for small-to medium-sized programs. This makes it a useful tool for 
problem-solvers. It accepts free-form or standard source statements. However, no permanent object 
program is produced, and some execution speed is sacrificed for fast compilation. Whenever the 
programmer need to link separately compiled programs and subroutines, when he is working with 
very large programs, or when he wants to produce an object program he can save, he will use the 
FORTRAN (G1) compiler. He may develop and test his program with Code and Go FORTRAN, 
and then compile it a last time with the FORT command. The TSO CONVERT command will 
change free form source statements to fixed form or vice versa. Code and Go FORTRAN is 
discussed in greater detail in the chapter ‘Problem Solving.” 


Entering the Source Program 


The programmer uses the EDIT command to create a source program. An operand of the EDIT 
command informs the syntax checker what FORTRAN compiler is going to be used. As the 
program source statements are entered, the FORTRAN syntax checker processes each line, 
interrupting the input sequence if it detects an error. 


Compilmg a FORTRAN Program 


When the programmer finishes entering the source program, he saves his data set with the SAVE 
subcommand, and, to invoke the FORTRAN IV (G1) compiler, switches to command mode to enter 
the FORT command, or stays in edit mode and uses the RUN subcommand. Operands of FORT 
allow him to specify various compiler options: whether or not a listing is to be produced, the 
contents of the listing, where it is to be printed or stored, whether or not an object program is to be 
produced, whether diagnostics are to be sent to the terminal, and whether the program is to be 
compiled for execution with FORTRAN Interactive Debug. All operands except the input data set 
name can default to standard values. 


As the compiler processes the program, it may find program organization errors that were not 
detected by the syntax checker on a statement-by-statement basis. Compiler diagnostic messages are 
sent to to the terminal, along with the statement in error, and a pointer to the field in error, if 
possible. Preceding the source statement is the line number assigned by EDIT when the source 
program was entered. The line number allows the programmer to use the EDIT subcommands to 
correct the statement quickly, without listing the entire program. 


When the program compiles successfully, the programmer can print an error-free listing, and use 
the LOADGO command to load his program for execution. 


PL/I 


The PL/I programmer can use the following language processors from the terminal: 
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e ITF: PL/I. 

e PL/I Optimizing Compiler. 
e PL/I (F) Compiler. 

e PL/I Checkout Compiler. 


The ITF: PL/I Program Product supports a subset of the PL/I language designed for solving 
problems at the terminal. It is provided by a compiler that offers two types of processing: a rapid 
compile-and-execute sequence for small- to medium-sized programs, or line-by-line interpretation 
and execution of PL/I statements as they are entered. ITF: PL/I is described in the chapter, 
‘Problem Solving.” 


The PL/I Optimizing Compiler, an IBM Program Product, is a language processor for use in 
either the background or the foreground environment. For the foreground environment, the compiler 
incorporates a prompter, which allows the user to invoke it with the PLI or RUN commands. 
Compiler options allow the user to request diagnostics and listings formatted for the terminal, or to 
request termination of compilation if syntax errors are found. 


The PL/I programmer can also use the PL/I (F) compiler from the terminal, but no special 
prompting or output format is available. The F-level syntax checker can be used to scan source 
statements as they are entered or to scan complete programs. The PL/I (F) compiler cannot be 
invoked with the PLI or PLIC commands. 


The PL/I Optimizing Compiler implements a more comprehensive set of PL/I than previous 
compilers and offers a choice of fast compilation, optimization for speed of object program 
execution, or optimization for minimum object program size. A subroutine library is required during 
linkage editing of a compiler output module. A second library is required for execution of the object 
program. Each library is available as an IBM Program Product: 


e OS PL/I Resident Library. 
e OS PL/I Transient Library. 


The PL/I Checkout Compiler is a two-stage processing program which translates and interprets 
(executes) PL/I programs. It can be used in either the batch or TSO environment of the IBM 
System/360 Operating System and supports the same level of language as the PL/I Optimizing 
Compiler. 


Using the checkout compiler in a TSO environment will often enable you to check out a PL/I 
program in one session at the terminal. Its conversational checkout features allow you to 
communicate with the compiler during processing. The compiler prints messages and listings at the 
terminal (as requested by the TERMINAL option) and you can respond with PL/I subcommands, 
or PL/I statements for immediate execution. The subcommands allow you to change compiler 
options, request more information, copy output files at the terminal, make temporary modifications 
to the PL/I program (during interpretation only), and either continue or terminate processing. The 
OS PL/I Transient Library is required during execution. 


You can also communicate with the PL/I program when it is being interpreted by using the 
conversational I/O feature of PL/I. 


Entering a PL/I Program 


The programmer uses the EDIT command to create his source program and save it as a data set. He 
can request EDIT to assign a line number to each line of his source program as he enters it. If line 
numbers are assigned, he can request the PL/I Optimizing Compiler or the PL/I Checkout 
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Compiler to use them in diagnostic messages, instead of statement numbers. The programmer can 
use the line number to retrieve the erroneous source statement, correct the error, and invoke 
another compilation, all without having the complete listing displayed at the terminal. 


Compiling a PL/I Program 


To invoke a compiler, the programmer uses either the RUN command, the PLI or the PLIC 
command. RUN can be used as a subcommand of EDIT, allowing the user to correct errors without 
entering the EDIT command again. RUN causes a complete compile-load-go sequence but does not 
produce a permanent object program. RUN is normally used during the initial compilations to check 
for source language errors. When a program is debugged, the PLI command can be used to produce 
an object program and a full listing. The object module can be loaded for execution or linkage 
edited into a program library for use as a load module. Whether invoked by RUN, or PLI, the PL/I 
Optimizing Compiler directs diagnostic messages to the terminal, in either a full or an abbreviated 
format. During testing, the programmer can have traces and other output generated by PL/I 
program checkout facilities displayed at the terminal. The PLIC command invokes the PL/I 
Checkout Compiler. 


Program Execution 


Programs produced by the compiler can be executed in either the background or the foreground. In 
the foreground I/O can be directed to the terminal by allocating a PL/I file, such as SYSIN or 
SYSPRINT, to the terminal with the ALLOCATE command. In the background these same files can 
be directed to data sets or unit record devices. 


Assembler Language 


Like programmers who use the higher level languages, the assembler language user enters his source 
program statements with the EDIT command. Assembler (F) accepts free form input, but the tab 
setting facilities of EDIT allow the user to create a formatted listing. On request, EDIT assigns line 
numbers to the source statements, which are later referred to by diagnostic messages produced 
during assembly. Line number or context editing is always available to correct errors, modify source 
statements, or add comments. 


Assembling the Program 


When the programmer completes his source program and saves it, he invokes Assembler (F) with 
the RUN or ASM commands. The use of these commands requires the TSO Assembler Prompter 
Program Product. Operands of ASM give him control over the listing format, disposition of output, 
and diagnostic messages. 


Assembler diagnostic messages sent to the terminal include the statement in error, if possible; 
both the EDIT-assigned line number and the assembler-assigned statement number; and an 
explanation of the error. Usually, the user will not need to have the complete listing displayed in 
order to obtain an error-free assembly. Using the line numbers in the diagnostic messages, the 
programmer can quickly locate and fix source statements errors with the edit mode subcommands. 


Test Mode 


When assembly completes without error, the programmer creates a load module with the LINK 
command, and uses the TEST command to bring it into storage. The TEST command processor uses 
the symbol table produced by the assembler and linkage editor, which gives the address and 
attributes of each symbolic name used in the source program. Before passing control to the program, 
TEST allows the user to establish initial values to be passed to the program as test data, and to set 
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up breakpoints where execution is to be interrupted for displays, dumps, and other debugging 
activity. The user can refer to points in the program by symbolic names, absolute relative or indirect 
addresses. 


To display storage and register contents, the programmer uses the LIST subcommand. specifying a 
register range or address range, or a list of symbolic names. Special forms of the LIST subcommand 
provide standard formats for control blocks such as the TCB, DEB, DCB, and PSW. LIST will also 
provide a current map of user storage. List output can be directed to either the terminal or a data 
set. 


Other TEST subcommands allow the programmer to load additional programs into storage, to 
delete or replace programs in storage, to issue GETMAIN and FREEMAIN as subcommands from 
the terminal, to define the location and attributes of symbols not in the symbol table, and to start 
and stop program execution. 


Other Compilers 


Any language processor designed to execute under the operating system can be invoked from a TSO 
terminal. A compiler, like any other program in load module form, is invoked with the CALL 
command. Options to invoked with the CALL command. Options to control the execution of IBM 
compilers -- such as LOAD or NOXREF -- are entered with the CALL command, in the same form 
as they would be specified in the PARM field of an EXEC statement in a background job stream. 


Before a language processor is invoked, the necessary input, output, and utility files must be 
allocated under the names expected by the processor. For the compilers invoked directly by their 
own commands (Full American National Standard COBOL Version 3 or 4, FORTRAN IV (G1), 
PL/I Optimizing Compiler, PL/I Checkout Compiler, ITF: PL/I, ITF: BASIC, Code and Go 
FORTRAN, and Assembler (F)), the necessary allocations are performed by initialization programs 
called before the compilers. 


Since the ALLOCATE statements necessary for a particular compiler are always the same, it is 
easiest to define them in a command procedure to be used for invoking that compiler. The function 
of the command procedure is the same as the cataloged procedures used to invoke compilers in the 
background: to save the user the trouble of entering a set of unchanging statements each time the 
compiler is invoked. Command procedures can be defined, either by individual users or by the 
installation, for any processor. 
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Problem Solving 


To meet the needs of users who may not be professional programmers, three problem-solving 
languages are available as IBM Program Products with TSO: ITF: BASIC, ITF: PL/I, and Code and 
Go FORTRAN. ITF: BASIC is a simple, algebra-like language that can be quickly learned, yet it has 
the power to perform complex mathematical calculations. ITF: PL/I is a subset of the full PL/I 
language. ITF: PL/I can be used in two ways: statements can be interpreted and executed as they 
are entered (desk calculator mode); or they can be collected into procedures for compilation and 
execution aS programs or subroutines. Code and Go FORTRAN provides the full FORTRAN IV 
language for terminal users. It has a very fast compile-and-execute sequence, carried out entirely in 
main storage. Code and Go FORTRAN accepts free-form or standard form source statements. 


All three languages have statement-by-statement syntax checking as the programs are keyed in, and 
additional diagnostics are set to the terminal for errors detected during compilation and execution 
phases. For the ITF: BASIC and PL/I languages, the test mode allows the user to monitor program 
execution with breakpoints and traces, to inspect and reset the values of variables and to modify 
main storage during execution. Code and Go FORTRAN supports both the compile-time debug 
facility and the use of FORTRAN Interactive Debug. 


Programs in any of the three languages are created, and can be run, in edit mode. Whenever 
necessary, the user can use EDIT to replace or modify source statements. For small to medium-sized 
programs performance is better in edit mode than in command mode, since the source statements 
and, in the case of Code and Go FORTRAN, the object program, can be kept in main storage and 
do not have to be read in from auxiliary storage. 


ITF: BASIC 


The ITF: BASIC Program Product is derived from the BASIC language created for time sharing use 
at Dartmouth College. With TSO, the BASIC user logs on to the system, then enters the EDIT 
command. In the input mode he enters successive statements to define his problem. If the system 
detects a syntax error, he is notified immediately so that he can correct the faulty statement before 
continuing. The user can defer syntax checking until compilation. When all his statements have been 
entered and syntax checked, the user issued the RUN subcommand to compile and execute the 
program. An operand of the RUN subcommand specifies whether he wants to execute with short 
precision (6 significant decimal digits) or long precision (15 digits). Programs and data can be saved 
from one session to the next, or deleted after use. 


ITF: PL/I 


The ITF: PL/I Program Product is a subset of the full PL/I language, suited to problem-solving 
because of its simplicity and ease of use. For example, there are no arithmetic conversion rules to 
remember: all data is kept in decimal floating-point format. The language is compatible with PL/I as 
provided by the PL/I (F) compiler, except that source language programs are stored with 
variable-length records and some arithmetic data formats that would default to fixed-point binary in 
full PL/I are floating-point decimal in ITF: PL/I. A utility command, CONVERT, is provided to 
format ITF: PL/I source programs for submission to a batch PL/I compiler, if the user wants to 
create an object program. 


ITF: PL/I can be used under either the EDIT or the CALC commands. Under EDIT, statements 
are collected into a program. When the program is complete, the RUN subcommand is used to 
compile and execute it. Under the CALC command, statements are interpreted and executed as they 


40 TSO Guide (Release 21.7) 


are entered. Statements are discarded as soon as they have been executed. Variables, however, are 
all defined as “‘static externals’” and kept in a table in main storage, where they can be refered to by 
subsequent ITF: PL/I statements, or displayed at the terminal. The table of variables created during 
a session using the CALC command can be saved in a data set for use in later sessions. 


ITF Test Facility 


When a user invokes an ITF: PL/I or BASIC procedure for execution, as an option he can specify 
that the program is to be tested. In this case, the system allows the user to set breakpoints in the 
program before it is started, and to set up program traces and displays of variables. All output from 
the testing routines is displayed at the terminal. When the program is interrupted by a breakpoint, or 
when the user hits the attention key, he can display and modify variable values, modify test 
procedures, and then restart the program at the point of interruption. The ITF testing subcommands 
are a subset of the TEST subcommands available for the programming languages. 


Syntax errors in an ITF: PL/I source statement are detected as soon as the statement is entered, 
and the user is notified to correct the statement. The user can request deferral of syntax checking to 
compile time. When operating under EDIT, some errors will only be detected at compile-execute 
time. In this case, a message is sent to the terminal, and the user is returned to the edit mode to 
correct the error in the source prograin. 


Code and Go FORTRAN 


For the many problem-solvers who are familiar with the FORTRAN programming language, the 
Code and Go FORTRAN Program Product is available for use from the terminal. The user creates 
his program, and optionally has it syntax-checked, with the EDIT command. He uses the RUN 
subcommand or the GOFORT command to invoke the Code and Go FORTRAN compiler. The 
source program is converted to an object program in main storage. As soon as the object program is 
complete, control is passed to it, except where TEST has been specified for execution with 
FORTRAN Interactive Debug. In this case, the TESTFORT command is used to invoke execution 
of the compiled program. The compiler used for Code and Go FORTRAN bypasses certain object 
code optimization processing for greater compilation speed. 


Free-Form Statements: Code and Go FORTRAN does not require statements to begin in column 7. 
If a statement has a label, the statement can immediately follow the label. If it has no label, it can 
start in column 1. 


A utility command (CONVERT) is available to change free-form source statements to fixed 
form, if a user wants to submit them to one of the batch FORTRAN compilers after developing and 
testing them in free form. Code and Go FORTRAN will also accept the standard format. 
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System Summary 


This chapter introduces the major control] and service routines that have been added to the MVT 
control program for time sharing. It identifies points where the installation can control system 
execution, and where modules can be modified or replaced for specialized applications. 
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Figure 2. TSO Control Flow Diagram 


Figure 2 is a generalized diagram of the flow of control through the system, showing several 
levels of control under the MVT control program. The portion of the system directly concerned with 
time sharing can be divided into five levels: 


1. At the highest level are the Time Sharing Control and the TCAM Message Control Program 
tasks. The Time Sharing Control task handles system-wide functions such as the initialization 
procedure required when the operator starts time sharing, and the swapping of foreground jobs. 
The Message Control] Program is a part of the Telecommunications Access Method (TCAM) and 
handles all I/O for remote terminals. 


2. Below the Time Sharing Control task is the Region Control task for foreground regions. The 
Region Contro] task supervises the quiescing and restoring of job activity before and after 
swapping. Conceptually, there is one Region Control Task for each foreground region, however, 
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since the Region Control Task is composed of reenterable code residing in the TSC region, only 
one copy exists. 


3. The LOGON/LOGOFF Scheduler is invoked by the Region Control task whenever a user wants 
to log on or off the system. The LOGON routine identifies the user to the system, and defines 
his foreground job using parameters in the LOGON procedure, user profile, and operands of the 
LOGON command. 


4. LOGON invokes a problem program specified by the user’s LOGON procedure at the next level. 
This is normally the TSO Terminal Monitor Program, which handles TSO and user-supplied 
commands. 


5. Command processors and other application programs execute at the lowest level of control. 


These levels are conceptual only, and are not defined by priorities or locations in main storage. 
Through the course of this chapter a more precise system flow diagram will be built. However, some 
overall design features of the system are apparent from even the simplified picture in Figure 2: 


e TSO is highly modular -- built up from small components with well-defined interfaces -- and 
therefore flexible and adaptable to local needs. The Terminal Monitor Program and the Message 
Control Program are designed to be modified or replaced by the installation for a specialized 
application. 


e Each level of control also provides an opportunity for the system to recover from failure. For 
instance, abnormal termination of a command processor or other problem program is handled by 
the Terminal Monitor Program. Only the user who invoked the failing program is affected -- and 
he is given an opportunity to recover the program through the TEST facility. Users at other 
terminals are completely protected. 


The Time Sharing Driver 


Before discussing the individual control routines in greater detail, one program must be added to the 
control flow diagram. The Time Sharing Driver isolates in one component the decision-making 
algorithms for the division of system resources among all the users of the system. By passing 
parameters to the Driver with the START command or from the system parameter library, the 
installation controls the various scheduling algorithms to gain the desired performance for its job 
mix. These “tuning” parameters and the algorithms are discussed in the last section of this chapter. 


As shown in Figure 3, the Driver has a unique relationship to the other control routines. It 
cannot be logically assigned to one of the control levels, but is used as a service program by all the 
levels from the MVT supervisor down to the Terminal Monitor Program. The calling programs 
inform the Driver of events throughout the system -- time slice end, user waiting for LOGON, job 
waiting for input, etc. From this stream of information, the Driver maintains a current picture of the 
system load and activity. Based on this picture, the Driver orders actions such as swapping, changes 
in priority, and assignment of a user to a particular region. 


The Driver component itself is completely insulated from the rest of the system by the Time 
Sharing Interface Program, which accepts all calls to the Driver, then passes them through a 
standard interface to the Driver itself. The Driver returns parameters to the Interface Program that 
request various actions by the other control routines. Thus, an installation can modify or replace the 
Driver -- effectively, provide its own system scheduler -- without modifying the system 
implementation programs. The operator uses the START command to specify which Driver -- the 
standard one or an installation-written one -- is to be used. 
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Figure 3. The Time Sharing Driver 


Control Routines 


The following paragraphs discuss the functions of each of the TSO routines. Although the TCAM 
Message Control Program logically shares the highest Jevel of contro] with the Time Sharing Control 
Task, it is discussed last. 


The Time Sharing Control Task 


The Time Sharing Control task, as shown in Figure 4 handles all functions affecting the entire time 
sharing portion of the system. This includes responding to the START, MODIFY, and STOP 
operator commands, and handling the swapping of foreground jobs into and out of main storage. 


When the operator enters the START command for TSO, and initialization module of the TIme 
Sharing Control is given control. The initialization module calculates the size of the Time Sharing 
Control region that will be needed and obtains it from the main storage management routine of 
MVT. In this region, the Time Sharing Control task builds the control blocks and buffers the system 
will need, and invokes a Region Control task for each foreground region. 


The installation may override the calculated TSC region size by specifying the size it wants in 
SYS1.PARMLIB or on the START command. This may be necessary if an installation written 
Driver has greater main storage requirements than the Driver supplied with TSO. 
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Figure 4. The Time Sharing Control Task 


While the time sharing system is operating, the major function of the Time Sharing Control task 
is the swapping of foreground jobs into and out of main storage. Swapping is handled at this level 
so it can be optimized on a system-wide basis when multiple foreground regions are active. A swap 
out is scheduled whether a channel is free or not. 


The Time Sharing Control task maintains an input queue and an output queue for swap requests 
(one of each set if parallel swapping is being used). It builds a channel program for each swap 
request. A program-controlled interruption (PCI) will occur near the end of each channel program. 
When the interruption occurs, an exit routine selects the next channel program to execute. The exit 
routine inserts a transfer to the next channel program at the end of the current channel program. 
Thus as the number of requests increases, the swap process is carried out by a never-ending channel 
program. Seek time is minimized by attempting to swap jobs out to the direct access area from 
which the last job swapped in, or if this is not possible, by using the free space closest to the 
current arm position. 


In determining what portion of a foreground region to swap out, the Time Sharing Control task 
uses a map of the foreground job created by the Region Control task. Each entry in the map 
identifies the starting address and length of a section of the region that the job is using. The number 
of entries in this map is the same for every job and is specified by the installation in the system 
parameter library. If there are too few entries, inactive main storage must be included (and 
swapped). A large number of entries cuts down on the amount of inactive storage that has to be 
swapped, but adds to processing overhead. 


When the operator enters a STOP command to shut down the time sharing operation, the Time 
Sharing Control task initiates a logoff for each active user. When all users are disconnected, the 
Time Sharing Control task ensures that all the system resources that had been assigned to it are 
returned; the Time Sharing COntrol task then terminates, returning its main storage region to the 
system. 


If any users cannot be logged off, the Time Sharing Control task cannot terminate. The operator 
is given the facility to force’ TSO to terminate even if it appears that normal STOP processing 
cannot be completed. For further information on "forced'’ STOP, see message IKJO24D in IBM 
System/360 Operating System: Messages and Codes, GC28-6631. 
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The Region Control Task 


A major function of the Region Control task is quiescing and restoring foreground job activity 
before and after swapping. Conceptually, there is one Region Control task for each active 
foreground region, invoked by the Time Sharing Control task although only one copy exists in the 
TSC region. Figure 5 shows a single Region Control task under the Time Sharing Control task. 


Before a foreground job can be swapped out of main storage, any activity associated with it must 
be brought to an orderly halt, or set up to be handled by some supervisor routine that will be 
remaining in main storage. This includes removing control blocks associated with the job from 
system queues, or flagging them as inactive. 





Figure 5. The Region Control Task 


Quiescing of I/O activity is initiated by the Region Control task (at the request of the Driver), 
which issues the Purge Supervisor Call for each task associated with the foreground job. The Purge 
routine removes I/O requests from the I/O Supervisor’s queues of pending requests if they have not 
yet been initiated. If a request has been started, that is, if data transfer is already taking place, it is 
allowed to complete before the job is marked ready for swapping. The control blocks associated 
with unstarted requests are stored in the foreground region where they will be swapped out of main 
storage along with the job. 


I/O requests that address the terminal are an exception to the quiescing procedure because of 
their long completion time. These requests are handled through the TSO interface with TCAM and 
are buffered in supervisor main storage, not in the foreground region. Data can be written or read 
to these buffers whether the job is present in its main storage region or not. 


Many control blocks, like the I/O requests mentioned above, reside in the foreground region. For 
background jobs, these control blocks would be created and maintained in the System Queue Area, 
a section of main storage set aside for this purpose during nucleus initialization. Foreground regions, 
however, each contain a Local System Queue Area to hold control blocks. As part of quiescing, the 
Region Control task removes pointers to these control blocks from system queues. The blocks can 
then be swapped out of main storage along with the foreground job. The only control blocks for 
foreground jobs that are assigned in the System Queue Area (and remain in main storage) are 
requests for timer interruptions, operator replies, and assignment of resources through ENQ. 


When a job is swapped into main storage by the Time Sharing Control task, the Region Control 
task receives control to restore the I/O requests it intercepted at swap out time, and to return the 
control blocks associated with the job to the appropriate system queues. 
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LOGON/LOGOFF 


The LOGON/LOGOFF Scheduler routine performs the same functions for foreground jobs that the 
reader/interpreter and initiator do for background jobs. When defining a foreground job, LOGON 
uses many of the same programs as subroutines. 


When LOGON is invoked by the Region Control task, as shown in Figure 6, it is swapped into 
the foreground region. A copy of the LOGON/LOGOFF Scheduler for each foreground region is 
kept in the swap data set, reducing the amount of initialization time needed. LOGON, and all 
routines below it in the control flow diagram, execute from the foreground region, and are swapped 
in and out of main storage. LOGON first validates the user’s identification and password in the 
User Attribute Data Set, and reads in the rest of the user profile. From the profile and any operands 
entered with the LOGON command, LOGON builds, in main storage a JOB and an EXEC 
statement that define the foreground job. The EXEC statement names the LOGON Procedure 
specified by the user, and the procedure in turn specifies the name of the program to be invoked. 
The procedure also contains DD statements for data sets the user always wants allocated to him, 
and some special DD statements that save control block space for data sets he may allocate later, 
dynamically. 
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Figure 6. The LOGON/LOGOFF Scheduler 


The JOB and EXEC statements built by the LOGON routine are passed to the reader/interpreter 
to define the resources required by the job, and then to the initiator for allocation of the resources 
-- direct access storage space, main storage control blocks, etc., -- and invocation of the program. 
Figure 7 shows the linkage scheme used during LOGON. Use of the system reader and initiator 
ensures that foreground jobs are compatible with normal background jobs, appearing to the system 
as a job consisting of a single step. 


The LOGON/LOGOFF Scheduler executes in the user’s foreground region. Assignment to that 
region is provisional until LOGON determines the correct size for the user’s needs. If a larger region 
is appropriate, LOGON can, through the Region Control task and the Time Sharing Control task, 
request that the Driver assign a different region. If a region switch is made, the job information 
LOGON has already gathered is left in a supervisor buffer. The Driver, through the Time Sharing 
Control task, causes LOGON to be invoked in the new region, where processing can proceed. 
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Figure 7. LOGON Linkage 


The LOGON routine is also brought into a region whenever a user enters a LOGOFF command, 
or a second LOGON command, during a session. For logoff, the LOGON routine ensures that all 
resources have been returned to the system, and calls the accounting routines to update the user’s 
Statistics. A second LOGON command during a session also causes logoff processing, but it is 
immediately followed by re-logon. The new logon may request a different logon procedure or region 
size. When a region size is supplied for the new logon, the IBM supplied Time Sharing Driver will 
only assign a new region if the user’s present region cannot satisfy the size requirement or has been 
made unavailable for LOGON by the operator’s MODIFY command. 


The Terminal Monitor Program 


For users of the TSO command language, the program named in the EXEC statement of the 
LOGON Procedure is the Terminal Monitor Program. Users of locally-provided command systems, 
or terminal monitors “‘dedicated”’ to some local application, can specify these programs in the 
LOGON Procedure. If necessary for security reasons, user access to particular applications can be 
controlled through the profiles in the User Attributes Data Set. 


The remainder of this discussion concerns only the IBM-supplied Terminal Monitor Program, as 
shown in Figure 8. Installation-written monitors must perform similar functions, and can use some 
or all of the service routines described below. 
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Figure 8. Terminal Monitor Program 
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When the Terminal Monitor Program receives control from LOGON, it is passed a pointer to the 
user profile. The profile contains information to control the environment of the current session -- 
the user identification to append to data set names, whether the user wants to be prompted for 
command information, whether he wants numerical message identifiers included in messages to the 
terminal. 


During a session, the Terminal Monitor is called on to handle four conditions: 


e A command processor or user program is completing, and a new command must be requested. 
e A command processor or user program is terminating because of an error. 

e The user hit the Attention key, interrupting the current program. 

e A CANCEL operator command is forcing a LOGOFF for the user. 


To invoke a command processor, the Terminal Monitor Program uses the command name to 
search the command library or libraries for the processor load module. When it is found, an 
ATTACH macro instruction is used to invoke it. When the command processor completes, the 
Terminal Monitor issues a DETACH for it, and writes a READY message to the terminal, indicating 
another command may be entered. 


When a command processor or a user program invoked by a command (CALL, RUN, etc.) 
terminates because of an error, control is passed to a Terminal Monitor Program routine that 
notifies the user of the error condition and allows him to enter a new command. If the new 
command is TEST, abnormal termination processing (ABEND) is cancelled and control is passed to 
the TEST processor so the user can examine the failing program and attempt to recover. If the new 
command is not TEST, the failing program completes abnormal termination and the new command 
is processed. 


When a user hits the attention key, or when a attention interruption is simulated for terminals 
without an attention key, the Terminal Monitor Program attention routine is given control, unless 
the currently executing program (a command processor or user program) has specified an 
attention-handling routine of its own. The Terminal Monitor Program attention routine gets a line 
from the terminal. If it is a program status inquiry such as TIME, the Terminal Monitor Program 
handles the inquiry and does not cancel the interrupted program. If a new command is entered, the 
interrupted program is cancelled and the Terminal Monitor Program invokes the new command 
processor. If the user enters a null line, the interrupted program is restarted at the point of 
interruption although the current content of the buffers are lost. 


When the operator or a control user enters the CANCEL command to force a user logoff, the 
Terminal Monitor Program terminates any program the user may have running, and returns to the 
LOGON routine for logoff processing and accounting. 


TEST 


The TEST processor is handled differently than other command processors, since it must be able to 
control the execution of programs (including command processors) being tested. The TEST routine 
executes at the same level as the Terminal Monitor Program -- receiving control via a LINK, rather 
than a ATTACH, macro instruction. 


TEST reads successive subcommands from the terminal or a command procedure. Each 
subcommand requests some action -- modification of the tested program’s registers or storage areas, 
insertion of breakpoints in the program, display of data. When the GO subcommand is encountered, 
the tested program is allowed to execute to the next breakpoint (an inserted SVC instruction) or to 
completion. When a breakpoint is encountered, TEST again receives control. It will then handle 
subcommands specified previously by the user, new subcommands entered from the terminal, or 
both. Another GO subcommand will restart the tested program. 


System Summary 49 


Service Routines 


The command processor service routines, as shown in Figure 9, are used by the Terminal Monitor 
Program, TEST, and command processor. In general, they perform services that are useful to all 
foreground programs, and their availability as subroutines saves repetitive coding in all the command 
processors. They can be called from programs written in Assembler language. 


Command Analysis: Two routines are provided for analyzing input lines to the Terminal Monitor 
Program and command processors. The Scan routine determines if an input line contains a 
syntactically correct command name, and, if it does, returns it to the calling program. The Parse 
routine continues the analysis of a command or subcommand by comparing the line to a parameter 
supplied by the calling program describing the permissible operands and default values. The Parse 
routine builds a new parameter list from this information, describing the options the user has 
selected, and returns it to the calling program. 
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Figure 9. Service and TEST Routine 


Terminal I/O: Four service routines are provided to handle command processor input and output for 
the terminal. Command processors normally accept input lines containing subcommands and data 
from the terminal, and send messages back to the terminal. However, a command processor may be 
invoked from a command procedure, and in this case, the input to the command comes from an 
in-storage list built by one EXEC command processor from the CLIST data set that contians the 
procedure. To allow the command processors to be independent of the source of input, I/O is 
handled through the Getline, Putline, and Putget service routines. 


Getline, Putline, and Putget use a push-down list to keep track of the current input source. 
Entries in the list represent a terminal, or an in-storage list. The in-storage list may be a command 
procedure or data. A fourth service routine, Stack, is provided to manipulate this list as the input 
source changes. 


When a command processor calls Getline for a line of input, Getline checks the list of sources to 
determine the current source and returns one record from that source. The caller need not know 
whether the input came from the terminal or an in-storage buffer. Putline also checks the list of 
input sources before sending output from the command processor. Some types of messages, 
identified by a code in the message identifier, are suppressed if the current input source is not the 
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terminal. For instance, it is not appropriate to issue a prompting message for command operand 
information if a command procedure is in progress. A return code to the caller indicates whether the 
message was issued or suppressed. Putget combines the function of Putline and Getline -- first 
sending a message, then returning one record. 


Dynamic Allocation: The Dynamic Allocation Interface routine handles data set allocation and 
manipulation for command processors. Dynamic allocation uses control block space reserved by DD 
DYNAM statements in the user’s LOGON Procedure. These control blocks are used over and over 
again when different data sets are needed, but at any one time, a user can have only as many data 
sets allocated as he has DD statements in his LOGON Procedure. Command processors call on 
Dynamic Allocation to allocate data sets, to free data sets, to search the system catalog for a 
particular data set or group of related data sets, and to concatenate or separate groups of data sets. 


In TSO a problem may arise from the multiple use of a Job File Control Block (JFCB) for an 
input data set. When the data set is opened, information supplied in the Data Set Control Block 
(DSCB) and the JFCB is used to fill any zeroed fields in the Data Control Block (DCB). The 
opening routines then do a reverse merge from the DCB back into the JFCB, this time filling any 
zeroed fields in the JFCB. If the same data set is subsequently opened using another DCB, the 
opening routines will retrieve information from the JFCB for fields not specified in the DSCB or on 
the DD card. This information could be faulty and could cause a program failure. Deleting the data 
set with the DELETE command and allocating it again with an ALLOCATE command will prevent 
these kind of errors. 


Command Processors and User Programs 


Although command processors vary widely in function, they have some initialization features in 
common. All call on the Parse routine to analyze the invoking command and prompt the user for 
missing or invalid operands, and all use the Dynamic Allocation routine to determine if necessary 
data sets are allocated and to allocate them if they are not. 


At this point, some command processors call on standard system processors to carry out the 
function desired. For instance, the TSO COBOL Prompter sets up a standard calling sequence 
according to the options selected by the user, and transfers control to the American National 
Standard COBOL compiler to compile the user’s program. Except for the special formatting of 
output and messages, the compiler operates exactly as it would in the background. 


User-written command processors, and other programs that are not defined as command 
processors, should avoid using the special Terminal Monitor Program-command processor interface if 
they are to be compatible with the background environment. The CALL, LOADGO, and RUN 
commands allow control information to be passed to background-compatible programs in exactly the 
same format as information in the PARM field of an EXEC statement. Data set allocation can be 
handled by ALLOCATE commands in a command procedure used to invoke the program. 


Terminal I/O 


The Telecommunications Access Method, or TCAM, handles all 1/O between remote terminals and 
jobs in the system. TCAM distinguishes between time sharing applications, with emphasis on direct 
control of the calling terminal, and other teleprocessing applications, where emphasis may be on 
queuing, formatting and routing of messages between remote terminals or between applications and 
remote terminals. 


The Message Control Program 


The Message Control Program is the TCAM control routine. It contains definitions and descriptions 
of the various terminals that can connect to the system, it has buffers for storing data going to and 
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coming from the terminals. It transfers data between its buffers and time sharing buffers. 


Most of the Message Control Program is written using a special set of macro instructions that is 
essentially a language suitable for defining the telecommunications network and specifying the 
handling of messages on the network and in the system. Macro instructions to generate a Message 
Control Program suitable for handling terminal I/O for time sharing are distributed with the TSO 
package. 


The Message Control Program executes as a problem program, in a main storage region with a 
nonzero protection key. Normally, it has the highest priority of the problem programs in the system. 
It must have a higher priority than the Time Sharing Control Task. 


Mixed Environment MCPs 


A TSO message control program can contain more than one message handler. A message handler is 
a sequence of code that routes terminal I/O to the appropriate program or terminal. A mixed 
environment Message Control Program contains the message handler for terminal I/O for TSO and 
in addition one or more non-TSO message handlers. 


In a mixed environment, the terminals used with TSO are allocated to the TSO message handler 
and the terminals used for TCAM applications to the TCAM message handlers. This is done 
through the macro instructions which define the message control program and through the cataloged 
procedure that starts the message control program. 


Terminal Interfaces 


A variety of interfaces to Terminal services are provided in TSO. The one suitable for a particular 
program depends on whether the program is defined as a command processor, and whether it must 
also be able to execute in the background environment. 


A supervisor call routine, reached through the TGET and TPUT macro instructions, provides a 
direct route for program I/O to a remote terminal. TGET and TPUT transfer data between the 
calling program and a set of buffers in the Time Sharing Control Task region, that are, in turn, 
emptied and filled by TCAM. Through TGET and TPUT, the calling program can control deletion 
or insertion of terminal control characters, and whether an output transmission is to break in on any 
input transmission in progress. A program using TGET and TPUT does not have to perform OPEN 
or CLOSE processing, and need not provide a DCB for the terminal. However, these macro 
instructions are available only to programs executing in the foreground. 


Programs designed to be command processors can call on the Getline, Putline, and Putget service 
routines used by the IBM-supplied command processors for I/O. As noted earlier, these service 
routines have the capability to switch the input source from the terminal to a buffer in main storage, 
and to suppress certain types of output if the terminal is not the current input source. 


The sequential access methods, BSAM (READ, WRITE, CHECK) and QSAM (GET, PUT), 
have been extended to call on TCAM (TGET, TPUT) when called from foreground programs for 
terminal I/O. This is the normal route for terminal I/O from programs that must be executable in 
the background as well as the foreground, or whcih are coded in a higher level language, such as 
FORTRAN or COBOL. 


Programs using BSAM and QSAM to reach the terminal use the standard macro instructions or 
I/O statements. When the program is executed, the DD statement or ALLOCATE command 
defines whether the I/O is for a data set or the terminal. No recompilation is necessary to switch 
from one to the other, only a change in the DD statement. 
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Getline, Putline, Putget and the sequential access methods all issue TGET or TPUT for the caller 
( when the I/O is for a terminal. Figure 10 shows this SVC routine handling calls from anywhere 
within the TSO system and passing the requests to the TCAM Message Control Program. 
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Figure 10. TCAM Message Control Program 
Multi-Terminal Message Processors 
Independent of TSO, the Telecommunications Access Method includes facilities for routing messages 
( received from remote terminal to queues for an application program, and transmitting replies 


generated by the applications program to queues for a terminal. In a system without TSO, such a 
message processing program must reside in main storage in one of the problem program regions, 
when it is to be available if one of the terminals in the telecommunication network sends a message 
that requires processing. With the addition of TSO, a terminal user logged on to TSO can execute a 
TCAM message processing program in a foreground region. He can do this by invoking it through 
the TSO command language, or by specifying it instead of the TSO Terminal Monitor Program on 
his LOGON procedure. The DD statements which define the process queues must be contained in 
the LOGON procedure. The program will be swapped in whenever needed, but will not occupy 
main storage space when it has no message to process. Unlike standard foreground jobs, which are 
associated with a single terminal, these message processing programs can handle GET/READ, 
PUT/WRITE TCAM oriented input/output from any terminal defined to the TCAM processing 
queues, through the QNAMES operand of the statements on the LOGON procedure. In addition, 
the standard TSO terminal interfaces, can be used to interact with the terminal executing the 

a Message Processing Program. For further information on message processing programs, see IBM 
System/360 Operating System: TCAM Programmer’s Guide and Reference Manual, GC28-2024. 


Overview and Storage Map 


Figure 11 is an overview of the complete time-sharing system as developed in the preceding 
sections. The picture is simplified in that it shows only one task at each level of control; there is 
actually one LOGON-Terminal Monitor Program for each user. Many of the programs themselves 
are re-enterable, and can be placed in an extension to the link pack area (LPA) built when the 
operator starts TSO. 
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Figure 11. System Overview 
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Figure 12 is a map of a typical main storage layout when TSO is operating. Almost all the 
additional storage requirement for TSO control functions is included in the Time Sharing Control 
Task region. This region is not assigned until the operator enters the START TS command, so the 
presence of TSO in the system has no effect on MVT throughput when time sharing is not active. 
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Figure 12. Typical Main Storage Map 


Time Sharing Algorithms 


As noted earlier in this chapter, the Time Sharing Driver is responsible for dividing the system 
resources -- most importantly, execution time -- among the various jobs in the system. So that this 
may be done effectively, the Driver is given a constant stream of information about the status of 
each job in the system -- whether it is ready to execute, whether it is waiting for I/O, whether it is 
in main storage or has been swapped out. 
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In a time sharing system, execution time is divided among the active foreground jobs and 
background jobs in brief time slices. A time slice must be long enough to perform a meaningful 
amount of processing, but not so long that the time between successive slices prevents quick 
response to conversational users. At the same time, time slices cannot be so short and frequent that 
system overhead for swapping and task switching becomes unreasonable. 


Balancing these factors depends partly on the number and type of jobs the system is processing: 
a solution for one job mix is not necessarily suitable for another job mix. The Driver’s time sharing 
algorithms -- the formulas it uses to calculate the division of execution time among the jobs in the 
system -- are based on several variables, many of which can be specified by the installation to tune 
the system for the local job mix. These variables may specify the system configuration, such as the 
number of foreground regions to be activated; they may request the Driver to use one of several 
algorithms it has for a particular calculation; or they may specify constants used in the algorithms. 
The variables are stored in a member of the system parameter library. 


Time Slices 


The Driver uses two important cycles in calculating time slices. One is the cycle of foreground jobs 
assigned to a region being swapped into the region, then back out to the swap data set on auxiliary 
storage. The average length of time to complete one cycle -swapping each job assigned to the region 
into it one time -- can be controlled by the installation for each foreground region. The length of 
time each job gets to remain in main storage during a cycle is called the major time slice. Figure 13 
shows a cycle of major time slices and swapping of jobs between the main storage region and a 
swap data set. 
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Figure 13. Queue Service Time 
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The other cycle used by the Driver is the allocation of execution time to the jobs in main storage. 
At a particular time there are likely to be several regions containing jobs ready to execute -- one or 
more foreground regions containing jobs swapped in for major time slices, and some background 
jobs in their own regions. The Driver divides the amount of time remaining until the next scheduled 
swap out among the jobs than are ready to execute, resulting in a minor time slice for each. For the 
duration of its minor time slice, each job has the highest effective priority of the problem programs 
(excluding TCAM). As in batch MVT, if the job cannot execute because it is waiting for I/O or 
some system resources, another job runs until the higher-priority job is ready again. 


Figure 14 shows the indirect relationship between major and minor time slices. A major slice is a 
fraction of a cycle of swaps into a foreground region, and 1s the length of a job’s stay in main 
storage. The minor slice is a fraction of the time remaining before the next scheduled swap out for 
any region (called the available execution time), and determines how long each job will remain at 
the highest effective priority; that is, how much execution time the job is alloted. 
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Figure 14. Minor Time Slice 


Major and Minor time slices can be calculated using only the number of ready jobs, and the 
available execution time. However the Driver algorithms have the capability to distinguish among 
varying user needs to provide the best service to each foreground job. The following two sections 
show how the tuning variables can be used to make the calculation of time slices most efficient for 
varying job mixes. 


Major Time Slices 
Swapping all the jobs into a foreground region from a queue of ready jobs assigned to that region is 


called servicing the job. The length of time used to swap all ready jobs on one queue is called the 
queue service time. The average queue service time for each queue of foreground jobs is an 
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installation parameter, passed to the Driver. The specified queue service time is divided by the 
number of ready foreground jobs on the queue, yielding a major time slice value for each job for 
that service cycle. As the number of jobs assigned to that queue increases, the major time slice value 
gets smaller. The time between services for each job remains fairly constant, which is important for 
conversational users expecting quick responses. 


A problem may arise when a large number of users are assigned to the queue. The division of 
queue service time may result in a major time slice too short to perform any meaningful amount of 
processing for the user, and the system will be spending all its time swapping. To avoid this 
condition, the installation specifies a minimum major time slice for each queue. Each job is 
guaranteed at least that amount of time in main storage on each cycle (provided it is ready to 
execute). When the minimum slice is being used, the actual queue service time will exceed the 
specified average queue service time. 


Multiple Region Queues: To meet varying needs of users performing different kinds of processing, 
the installation can establish multiple service queues for each foreground region. Queue service 
cycles can be rotated equally among these queues, or priorities can be specified among them. Each 
queue is assigned its own average queue service time. The installation can also specify that a queue 
is to be given multiple cycles before the next queue is serviced, or that it is to be serviced until 
empty -that is, until no jobs are left on the queue that are ready to run. 


Assignment to queues can be based on the amount of main storage the job is using, or the degree 
of interaction with the terminal, or both. The amount of main storage assigned to the job is called 
swap load, since it is a measure of the amount of I/O necessary to swap the job in and out of 
storage. A swap load limit can be specified for each queue. If a job’s storage needs grow beyond the 
limit, it is assigned to a lower queue, with a higher limit. The lower queues can be set up to receive 
fewer services, but longer major time slices at each service. Therefore the larger jobs will not have 
to be swapped so often. 


The degree of interaction with the terminal is measured by the amount of processing time used 
by the job since its last request for I/O to the terminal. A terminal I/O request is called an 
interaction, and the length of execution time between interactions is called interaction time or 
occupancy. Very long interaction times indicate the user is not currently processing conversationally 
-- perhaps he is compiling a program, or executing some long-running problem program. In this case, 
his job does not require the quick response times provided by the higher region queues, and can be 
moved to a lower queue where it will receive fewer, but longer, major time slices. Each queue can 
be assigned an interactive time limit, to allow for this differentiation. The occupancy and swap load 
limits for a given queue must be higher than the next lowest queue. 


Either the swap load or the interaction time limits can be suppressed when the time sharing 
operation is started for the day, but if both are suppressed, only one queue per foreground region is 
maintained. The rotation of service cycles around the queues for a region can also be made 
preemptive: any time a job on higher queue becomes ready to execute; for instance, if a terminal 
I/O request completes, the service cycle of any lower queue is interrupted to service the job on the 
higher queue. This scheduling scheme tends to make responses to trivial terminal requests very fast, 
while lengthening somewhat the response to requests requiring a lot of processing time. 


Region Assignment: The last factor involved in calculating major time slices is choosing a foreground 
region for the user logging on. The minimum region size needed by the user is stated in this 
LOGON procedure, and only those foreground regions large enough are considered. 


If a choice must be made among two or more regions, the system can try to balance the 
workload by assigning the new user to the region with the fewest logged-on users. However, this 
leaves open the possibility that a group of users all requiring a lot of execution time will be assigned 
to one region, while another region has a preponderance of users processing conversationally. 
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Neither group will receive the best service possible. To prevent this condition, the installation can 
specify that an average region activity be maintained for each foreground region. The average region 
activity is the number of jobs likely to be ready to execute (not waiting for terminal I/O, for 
instance) at the beginning of the next cycle of major time slices. A new user is then assigned to the 
region with the lowest region activity, which is not necessarily the region with the fewest logged-on 
users. 


The region activity estimate is based on the number of ready jobs on the region’s queues during 
recent major cycles. Values from more recent cycles are “‘weighted” in calculating the average. The 
weighting factor, called the “region activity decay constant,” is specified by the installation. Use of 
decay constant prevents wild fluctuations in the region activity because of a few cycles, but allows 
gradual change to reflect changing workload. 


Major Slice Variables: To summarize, the system programmer can specify the following variables 
affecting the major time slice calculation: 


e The maximum number of users logged on. 

e The number of foreground regions. 

« The method for assigning users to regions. 

e The number of service queues for each region. 

For each region queue, the following variables can be specified: 

e The average queue service time. 

e« The number of service cycles before advancing to the next queue. 
e The minimum major time slice. 

e« The swap load limit. 

« The interaction time limit. 


Variables can be omitted or ignored, if the job mix and workload allow simplification of the 
algorithm. In general, the more homogeneous the job mix, the more the algorithm can be simplified, 
dividing time almost equally among the jobs. Remember that the major time slice determines only 
how long a job remains in main storage, not how much execution time it receives. Calculation of the 
minor time slice, which determines execution time, is discussed next. 


Minor Time Slices ° 


The minor time slice is the result of dividing the available execution time among the regions of main 
storage containing either a ready foreground job or a ready background. Available execution time, in 
this sense, is the period from the time of the calculation until the next scheduled swap out. 
Whenever a major time slice expires, the calculation is repeated with the new number of ready 
regions. 


The minor time slice is not quite equivalent to a period of execution time -- a job may have to 
wait for I/O or some resource during its minor time slice. In this case, control is given to another 
region until the waiting job is ready again. If it does not become ready before its minor time slice 
expires, it may wait until the next cycle of minor time slices before executing again. 


All terminal jobs are assigned the same dispatching priority, so their Task Control Blocks (TCBs) 
are grouped together on the queue of active TCBs maintained by the operating system task 
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Supervisor. Because the dispatcher always searches this queue from the top when looking for the 
next task to receive control, there is an effective priority within the time-sharing TCB group based 
on the order in which the TCBs are found. The TSO control routines adjust this order to effect the 
dispatching of a task currently assigned a minor time slice. When the minor time slice of the top 
foreground job expires, its TCBs are moved to the bottom of the group. 


The installation can adjust or weight the fraction of available execution time assigned to each 
ready region, or it can suppress division of the time altogether. The system operator, or a control 
user, specifies how many regions are active, and how much execution time, if any, is to be 
guaranteed to jobs running in the background regions. Three possible methods of calculating the 
minor time slices, called simple, even, and weighted dispatching, are described in the following 
paragraphs. 


Simple Dispatching: In this case, the minor time slice is set equal to the available time, and assigned 
to the TCB at the top of the time-sharing TCB group (which will always be the job swapped in 
most recently). Expressed as an algorithm: 


MS = AT 


where MS is the minor time slice and AT is the available execution time, or the time remaining 
before the next scheduled swap out. 


If the operator has requested a percentage of execution time for the background regions, available 
time is reduced by that amount before the minor time slice is calculated. When the minor time slice 
expires, in this case before time for a swap out, the remaining time is assigned to TCBs representing 
jobs in the background regions, in whatever priority they may have. If no background percentage is 
requested, any background jobs will receive only the execution time that the foreground jobs cannot 
use. 


Simple dispatching is always used whenever only one foreground region is present in the system. 


Even Dispatching: When more than one foreground region is defined, the installation can specify 
even dispatching of the foreground jobs. In this case, the available execution time is divided evenly 
among the ready foreground regions. 


The algorithm is: 


AT 
MS = N 
where N is the number of foreground regions containing jobs ready to execute. As in simple 
dispatching, available time is reduced before the calculation by any guaranteed background 
percentage. 


The first minor time slice is assigned to the foreground job at the top of the group of 
time-sharing TCBs on the queue. When the minor slice expires, the TCBs associated with that job 
are moved to the bottom of the time-sharing group, and the next foreground job receives a minor 
time slice. 


Weighted Dispatching: The third way the minor time slice calculation can be performed is on a 
weighted basis. This method allows the system to compensate for jobs that are likely to spend much 
of their minor time slice in the wait state, usually because of pending I/O requests. (But not for 
pending terminal I/O, since a job waiting for terminal I/O is not swapped in, and never becomes 
eligible for a minor time slice.) Under weighted dispatching, the system keeps an estimated wait time 
percentage for terminal job, based on averages of time spent waiting by each job during previous 
major time slices. Jobs with a high estimated wait time percentage tend to be I/O-bound, and will 
donate much of their time slices to jobs with TCBs on the queue below them. Jobs with low 
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estimated wait time percentages tend to be compute-bound, and will use most of their minor time 
slice themselves. It is often desirable to assign the I/O-bound job a weighted, or longer, minor time 
slice to compensate for its “donation” of execution time to other jobs. 


To weight the minor time slices, the system forms a sum of the estimated wait time percentage of 
the jobs to be assigned minor slices in the current cycle. Each job is then given a fraction of the 
available execution time equal to its fraction of the total estimated wait time percentages. 


The algorithm is: 


This job's EWTS 
MS = ---~------------ x (AT) 
Sum of EWT&s 


where MS is the minor slice to be assigned to a terminal job, EWT% is the estimated wait time 
percentage, and AT is the available execution time for this minor slice cycle, again adjusted for any 
guaranteed background percentage. 


As an example, consider a minor time slice calculation for two foreground regions, one containing 
Job A, which is expected to wait 40 percent of it minor time slice; the other containing Job B, 
which is expected to wait only 10 percent. The sum of the estimated wait time percentages is 50 
percent. Job A gets 40/50, or 4/5, of the available execution time as its minor time slice. Job B is 
assigned 10/50, or 1/5, of the available execution time. However, Job B will probably be able to 
execute for about 40 percent of Job A’s minor time slice too (while Job A is waiting for I/O), and 
so will end up with under half the available execution time -- about what it would have been 
assigned on an equal division. Job A, however, will be able to get its I/O started, wait for it to 
complete, and still have some processing time left to handle the data or issue another I/O request. 
On an equal division of available time, its minor time slice might have expired before its first I/O 
request completed. 


The estimation of wait time percentage is made by updating a running average of a job’s wait 
time percentages at the end of every major time slice. In making the average, a weighting factor is 
used to emphasize recent usage over earlier usage. The weighting factor is called the wait time decay 
constant. Its purpose and function is similar to the region activity decay constant, and it can also be 
specified by the installation. Values appropriate for general job mixes are included in 
SYS1.PARMLIB. 
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Preparing a System for TSO 


This chapter is intended for the programmers and system analysts responsible for generating and 
maintaining a system with TSO. (The discussions assume that the reader is familiar with the System 
Summary chapter of this publication.) The discussions contain specific information needed to 
maintain or generate a system with TSO. 


For example, the discussion “Tailoring a Message Control Program” does not discuss the role a 
message control program plays in a TSO configuration, but rather provides the syntax and meaning 
of the macro instructions used to generate a message control program. 


This chapter includes discussions of how to: 
e Generate (or tailor) a Message Control Program. 
e Write the cataloged procedures used by TSO. 
e Specify TSO starting parameters. 
e« Tune the Time Sharing Driver and use TSO Trace. 
e Write an installation exit for the SUBMIT command processor. 
e Write an installation exit for the STATUS, OUTPUT, and CANCEL command processors. 


« Write a LOGON pre-prompt exit. 
Tailoring a Message Control Program 


A Message Control Program, (MCP), handles terminal I/O for TSO. An installation must tailor the 
MCP to match its needs. 


For further information about TCAM and Message Control Programs in general, see IBM 
System/360 Operating System: TCAM Programmer’s Guide and Reference Manual, GC30-2024. 


TSO includes a standard Message Control Program (MCP) to handle terminal I/O for those 
installations that use TSO for all their TCAM applications. An installation tailors a Message Control 
Program in three steps. First, three macro instructions must be assembled: LINEGRP, LISTTA, and 
TSOMCDP. The output of this assembly is a series of TCAM (Telecommuncations Access Method) 
macro instructions which must, in turn be assembled. The output of this second assembly forms an 
MCP that must then be linked edited into SYS1.LINKLIB. 


Mixed Environment MCPs 


If an installation requires a mixed environment Message Control Program, because of TCAM 
applications programs, (message processing programs), it must generate an MCP using TCAM 
macro instructions instead of the special TSO MCP generating macro instructions. The TCAM 
macro instructions are used to generate an MCP containing the TSO Message Handler, and any 
other message handlers for particular terminal applications, and the necessary terminal I/O control 
blocks. 


The communications lines which are to be used for TSO sessions can also be used for TCAM 
applications. 
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In addition to the standard TCAM macro instructions, the TSOMH macro instruction can be used 
to form a TSO Message Handler. 


The TSOMH macro instruction has one operand, CUTOFF, which specifies a maximum message 
length. The syntax of the TSOMH macro instruction is: 


TSOMH CUTOFF= finteger 
300 


CUTOFF= 
specifies the maximum number of bytes before the remainder of an input message is lost to the 
system. The value must be an integer between 150 and 65535; the default is 300. 


TSO-Only MCP 


The following is an explanation of each step of the generation of the MCP supplied with TSO: 


Step 1 - Assembly of the one or more LINEGRP macro instructions each followed optionally by 
one or more LISTTA macro instructions, all followed by the TSOMCP macro instruction. 
The resultant output is a temporary data set containing assembler language source 
statements -- TCAM macro instructions which constitute a Message Control Program, 
that will be used as input to Step 2. 


Note: Terminals may be attached to a 2701 through Dual Communication Interface A or B. The 
LINEGRP macro instruction assumes that all terminals are attached through interface A. If the 
terminals on a line group are attached through interface B, punch the output of step 1 and change 
the INVLIST parameter of the DCB for that line group. For further information, see OS/MFT and 
OS/MVT TCAM Programmer’s Guide, GC30-2024. 


Step 2 - Assembly of the TCAM MCP macro instructions generated within Step 1. The output of 
Step 2 is the MCP object module placed into a temporary data set. 


Step 3 - Linkage Editing of the object modules from Step 2 into SYS1.LINKLIB to create an 
executable MCP load module. 


Figure 15 shows the Job Control Language necessary to min these steps. 
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/ /MCPGEN Job card parameters 
//STEP1 ASMFC 


//KSM.SYSPUNCH DD DSN=&&TCM, DISP=(,PASS), 
// UNIT=SYSDA,SPACE=(CYL,(1,1)) 


//ASM.SYSIN DD * 
LINEGRP 
LISTTA 
LINEGRP 
TSOMCP 
END 


{* 
//STEP2 ASMFC , COND=(4,LT,STEP1.ASM) 


//ASM.SYSPUNCH DSN=&&0BJ,DISP=(,PASS), 
// UNIT=SYSDA,SPACE=(CYL,(1,1)) 


//ASM.SYSIN DSN=* .STEP1.ASM.SYSPUNCH, 
// DISP=( OLD, PASS ) 


//STEP3 PGM=LINKEDIT , COND=(4,LT,STEP2.ASM) 


//SYSLMOD DSN=SYS1.LINKLIB( LEDQTCAM ) ,DISP=SHR 


//SYSPRINT SYSOUT=A 
//SYSUT1 UNIT=SYSDA,SPACE=(1024,(50,20)) 
//SYSLIB DSN=SYS1.TELCMLIB,DISP=SHR 


//SYSLIN DSN=* .STEP2.ASM.SYSPUNCH, 
// DISP=( OLD, PASS ) 





Figure 15. Job Stream to Tailor MCP 


LINEGRP Macro Instruction 


The LINEGRP macro is used to define a line group, a group of terminals with similar characteristics: 
for example, a group of IBM 2741 terminals. The operands of the LINEGRP macro instruction 
specify: 


¢ The types of terminals in the line group. (TERM) 


e The ddname of the DD statements that define the communications lines as data sets. 
(DDNAME) 


e The number of lines, that is, physical device addresses in the line group. (LINENO) 
e The number of TCAM basic units, per terminal buffer. (UNITNO) 
e The translation tables to be used to translate from the terminal code to EBCDIC. (TRANTAB) 


¢ The character string identifying the transmission code being used when dynamic translation is 
required. (CODE) 


e Whether switched or nonswitched lines are used in this line group. (DIAL) 
e The polling interval for polled terminals in this line group. (INTVL) 


« The special features the terminals in this line group have -- that is, Transmit or Receive 
Interruption and for 1050, Text Timeout suppression. (FEATURE) 
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e The polling and addressing character of terminals in this line group, for 1050, 2260/2265, and 
3270. (ADDR) 


e The screen sizes for IBM 2260, 2265 and 3270 Display Stations. (SCREEN) 
e The number of terminals on each nonswitched line. (TERMNO) 


LINEGRP Macro Instruction Format 


Operation Operand 


(name )LINEGRP TERM=type 
DDNAME=ddname 
LINENO=number 
{UNI TNO=number | 
{TRANTAB=(table;table...)] 
{CODE=(string,string... )] 


DIAL= fYES 

NO 
[INTVL=number ] 

iene fess (eae ) (TOSUPPR)) 


NOBREAK, NOATTN, 
{ADDR=character string] 
[SCREEN=(integer, integer )] 
[TERMNO=( integer, integer )] 





TERM= 


Specifies the type of terminal making up this line group. Only one of the following can be 
selected: 


1050 -- defines a line group consisting of IBM 1050 Printer-Keyboards on either switched (dial) 
or non-switched (direct) lines. 

2741 -- defines a line group consisting of IBM 2741 Communications Terminals on either 
switched or non-switched lines. 

5041 -- defines a line group consisting of both IBM 2741s and IBM 1050s. The terminals in this 
line group must be on switched (dial) lines. 

3335 -- defines a line group consisting of Teletype Model 33 or Model 35 terminal or both. The 
terminals in this line group must be on switched (dial) lines. 

226L-- defines a line group consisting of IBM 2260 Display Stations connected on a local line. 

226R-- defines a line group consisting of IBM 2260 Display Stations, connected on a remote 
line, and optionally IBM 2265 Display Stations. 

327L-- defines a line group consisting of IBM 3270 display systems connected directly to a CPU 
channel. 

327R-- defines a line group consisting of IBM 3270 display systems connected on a remote line. 

3278S -- defines a line group consisting of stand-alone IBM 3270 display systems (IBM 3275 
Display Stations) connected on a remote line. 


DDNAME= 


Specifies the ddnames of the DD statements that define, as a data set, the terminal lines in the 
line group . These DD statements are found in the cataloged procedure that is used to start the 
MCP. 


LINENO= 


Specifies the number of lines in this line group. The value must be an integer between 1 and 51. 
To save storage space, code large line groups before smaller line groups. 


UNITNO= 
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Specifies the number of basic units per buffer for terminals in this line group. A basic unit is used 
by TCAM to construct I/O buffers. The default value is 1. 


TRANTAB= 
Specifies the translation tables to be used for this line group. If this parameter is omitted, all of 
the supplied translation tables that are valid for the terminal type specified by TERM= will be 
included except those marked with an asterisk. Terminal dependent characters may be translated 
to invalid EBCDIC characters. 


TERM= TRANTAB= Common Name 
1050 1050 
2741 CR41 Correspondence 
EB4 1 EBCDIC 
BC41* BCD 
5041 1050 BCD 
BC41* BCD 
EB4 1 EBCDIC 
CR41 Correspondence 
3335 TTYB TTY parity 
Liye MEY. Non=pari ty 
226L EBCD 
226R 2260 
2205 2265 
S275 EBCD EBCDIC 
327R EBCD EBCDIC 
ASCI* ASCII 
3278 EBCD EBCDIC 
ASCI* ASCII 


*Not used as a default translation table. 


Note: If more than one table is specified explicitly or implied by default, the MCP will use the 
CODE parameter to determine the proper translation table dynamically. For 3270 line groups, 
only one table may be specified. 


CODE= 
Specifies the character string use to determine the terminal character set. Each time a terminal is 
connected, the MCP translates the input line from that terminal using each of the translation 
tables specified in the TRANTAB operand. The MCP compares the translated result with the 
character string specified in the CODE= operand. When the MCP finds a match, it uses the 
appropriate translation table for that terminal from then on. 


The default is CODE=LOGON unless the TRANTAB operand specified both BC41 and EB41 
(2741 BCD and 2741 EBCDIC). If both EBCDIC and BCD characters sets are present in the 
line group, the default is CODE="LOGON. 


An installation can specify a maximum of four character strings other than LOGON, but each of 
them must be eight or fewer characters. 


DIAL= 
Specifies whether the line group is a dial (switched) line group. If this parameter is omitted, YES 
is assumed. DIAL=NO is required for TERM=226L, 226R, 2265, 327L, 327R, and 3278S. 
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INTVL= 
Specifies the poll delay intervals in seconds for polled lines. The value should be an integer 
between 1 and 255. If this parameter is omitted, a value of two is assumed for polled lines. Zero 
| is assumed for 2741, 3335, 226L, and 327L terminal types. 


FEATURE= 
Specifies the special features that define this line group: 


BREAK Specifies that terminals in this line group have the Transmit Interruption feature. 


NOBREAK Specifies that terminals in this line group do not have the Transmit Interruption 
feature. This operand should be specified when any of the terminals in the line 
group do not have the feature. 


ATTN Specifies terminals in this line group have the Attention feature (Received 
Interruption. ) 


NOATIN _ Specifies that terminals in this line group do not have the Attention Feature. 


TOSUPPR _ For 1050 terminals, this operand specifies that the optional Text Time-out 
Suppression feature is present. This operand applies only to 1050 terminals and 
should be specified only if all 1050 terminals in a 1050 or 5041 group have the 
feature. When specified read inhibit rather than read commands will be used unless 
Autopoll is also being used. 


The following table describes the features which may specified for the 1050, 2741, 5041, 2260, 
| 3270, and the 3335 (TWX); where: 


D = Default. 

A = Assumed. 

I = Invalid. 

O = Optional. 

Feature 1050 2741 5041 3335 2260 3270 
BREAK O D O A I I 

NOBREAK D O D I A A 

ATTN D D D A I I 

NOATTN O O O I A A 

TOSUPPR O A O* A I I 


*TOSUPPR is optional for the 1050 terminals ina 5041 line group. It is 
assumed for the 2741 terminals in the same 5041 line group. 


ADDR= 
Specifies the station identification character (1050), the two byte control unit device address 
| (226R,2265), or the two-byte control unit/device polling characters (327R, 327S) of the 
terminals in the line group. The character string should be the hexadecimal equivalent of the 
appropriate transmission code. 


Hexadecimal characters should be specified without framing characters. For example if the station 
identification character is “‘A’’, the correct specification is ADDR=E2, the hexadecimal 
equivalent of the 1050 transmission code for the character “A”, not ADDR=C1, the hexadecimal 
equivalent of the EBCDIC character “‘A”’. To find the hexadecimal equivalent of a given 
character in a specific transmission code, consult the component description publication. 


For the 1050, only the station identification character value need be specified; the component 
selection character values will default to the common polling and addressing values for input and 
output, respectively. 1050 multidrop is not supported. 
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This parameter is not valid for TERM=2741 or TERM=3335. This parameter is required for 
TERM=1050 or 5041. For configurations in which the addressing characters vary among the 

| different terminals in the line group, as in 2265 or 3270, the addressing characters should be 
specified using LISTTA macro instructions (see below) rather than the LINEGRP macro 
instruction. 


SCREEN= 
Specifies the screen dimensions of the display station(s) on the line. The first integer specifies the 
number of rows on the screen. The second integer specifies the number of characters per row. 
Standard IBM screen sizes are 12x80, 12x40, and 6x40 for the 2260 and 12x40 or 24x80 for the 
3270. Non-standard sizes will be accepted but a warning will be given. The default for this 
parameter is 12x80 for a 2260 and 24x80 for a 3270. 


TERMNO= 
Specifies the number of terminals attached to each non-switched line, used with TERM=226R, 
327R, 327S, and 2265. Each subparameter specifies the number of terminals attached to the 
corresponding relative line within the line group. The relative line numbers are determined by the 
order in which lines in the line group are defined with DD statements in the cataloged procedure 
used to start the MCP. 


LISTTA Macro 


The LISTTA macro instruction specifies variations in device address (ADDR) within a line group. 
One or more LISTTA macro instructions can appear after each LINEGRP macro instruction. Each 
LISTTA macro instruction modifies one line (RLN) within a line group. 


LISTTA Macro Instruction Format 


Operation Operand 


LISTTA RLN=integer 
[, ADDR=(chars ,chars... )] 
[, SCREEN=( integer, integer )] 





RLN 
Specifies the relative line number within a line group to which the attributes specified in this 
macro instruction apply. The relative line numbers are determined by the order in which lines in 
the line group are defined with DD statements in the cataloged procedure used to start the MCP. 
For example, RLN=1 refers to the line in the line group defined by the first DD statement in the 
cataloged procedure. 


ADDR= 

Specifies the alphabetic station identification character (1050), the two byte control unit and 

| device address (2260, 2265), or the two-byte control unit/device polling characters (327R, 327S) 
of the terminal(s) on this line. One character string must be specified for each terminal on the 
line. Subparameters must be specified in the order in which polling is to take place. Each 
character string should be the hexadecimal equivalent of the appropriate transmission code 
representation for the terminal involved. Hexadecimal characters should be specified without 
framing characters. 


Example: ADDR=(A0A1,A0A2) -- for a 2848 Model 2 with two IBM 2260 Display Stations 
attached. 


For a 1050, only the station identification character value need be specified. 1050 multidrop is 
not supported. 
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SCREEN= 
Specifies the screen dimensions of the display station(s) on the line. The first integer specifies the 
number of rows on the screen. The second integer specifies the number of characters per row. 
Standard IBM screen size are 12x80, 12X40, and 6x40 for the 2260 and 12x40 or 24x80 for the 
3270. Non standard sizes will be accepted but a warning will be given. The default for this 
parameter is 12x80 for a 2260 and 24x80 for a 3270. 


TSOMCP Macro 

The TSOMCP macro instruction: 

e Names the MCP (provides the CSECT name). 

e Defines the size of the TCAM basic units used to construct terminal I/O buffers. 
e Specifies which TCAM trace tables will be provided. 

e Specifies whether a cross-reference table will be included in the MCP. 


e Specifies whether the operator can change parameters when he starts the MCP. 


TSOMCP Macro Instruction Format 


Name Operation Operand 


name TSOMCP [UNITSIZ=number | 
[ TRACE=number | 
[| DTRACE=number | 
| LNUNITS=number | 
[OLTEST=number | 
[OPTIONS=( XREF , PROMPT ) ] 


Note: All operands are optional. 


name 
Provides the CSECT label for the generated program. This field is required. 





UNITSIZ= 


Specifies the size of a TCAM basic unit and must be a value between 41 and 255 inclusive. If 
omitted, the MCP uses a default value of 60. UNITSIZ should be a multiple of 8, plus 4 for 
efficient main storage usage. 


TRACE= 


Specifies the number of TCAM I/O trace table entries in the Message Control Program. The 
default value is zero. Maximum value is 65535. 


DTRACE= 


Specifies the number of TCAM Dispatcher Trace Table entries in the Message Control Program. 
The default value is zero. Maximum value is 65535. 


LNUNITS= 
Specifies the number of TCAM basic units to be provided in the buffer pool for creating line 
buffers for this MCP. A maximum of 65,535 may be specified. If this operand is omitted, the 
system will calculate a default value using the following algorithm: 


LNUNITS= 

2 x (number of terminals) x (UNITNO value) 
or (for 2260, 2265, or 3270) 

2.5 x (number of terminals) x UNITNO 
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where: 

UNITNO (as specified in each LINEGRP macro) represents the number of units per buffer for 
terminals defined in the associated line group. If UNITNO is omitted in the LINEGRP macro, 
the default value (1) is used. This means that each buffer will consist of one basic unit. 


If both the LNUNITS and UNITNO keywords are defaulted, the buffer pool created will consist 
of 2 buffers per terminal with each buffer being one basic unit in length. (PCI buffering is used 
for both input and output.) 


OLTEST= 
Specifies the number of 1024 byte blocks used for Online Test procedures. The value must be 0 
or an integer greater than 9 and less than 256. The default is 0, meaning Online Test is not used. 
For a system with display stations, the minimum value is 14 rather than 10. 


OPTIONS= 


XREF 


A cross-reference table including control blocks for each line will be included in the MCP. 
If this option is omitted, the cross-reference table will be excluded. 


PROMPT 


If PROMPT is specified, the system operator will be asked to enter parameters when 
TCAM is started. At that time he may enter and override some of the parameters specified 
when the MCP was assembled. The following TCAM parameters are ones which an 
installation may want to specify when it starts TCAM for TSO. The last parameter entered 
must be a “U” to end the prompting process. See IBM System/360 Operating System: TCAM 
Programmer’s Guide and Reference, GC30-2024, for a description of the INTRO macro 
instruction and the parameters which can be overridden. 


KEYLEN = integer 
K = integer 


Specifies the size of the basic units, with which the terminal I/O buffers are constructed. 
This corresponds to UNITSIZ= parameter. 


LNUNITS = integer 
B = integer 


Specifies the number of basic units which are used to build buffers. It corresponds to 
LNUNITS. The value must be between 0 and 65535. 


STARTUP = C 
Ss=C 


Specifies that a “‘cold”’ start is to be performed following a shutdown of the Message 
Control Program or a system failure. It is required if OPTIONS=PROMPT was specified on 
the TSOMCP macro instruction. 


CROSSRF= integer 
F = integer 


Specifies the number of entries in the cross reference table, a debugging aid. If 
OPTIONS=XREF is specified in the TSO MCP, one entry will be generated for each line. 
If the operator specifies fewer entries than there are simultaneously open lines, lines opened 
after the table is full will have no entries. 
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BS: 


TRACE = integer 
T = integer 


Specifies the number of TCAM I/O trace entries to be allocated; corresponds to TRACE= 
in the TSOMCP macro instruction. 


DTRACE = integer 
A = integer 


Specifies the number of entries in the TCAM Dispatcher Trace Table, corresponds to 
DTRACE= in the TSOMCP macro. The Dispatcher Trace Table is a debugging aid that 
keeps a sequential record of TCAM subtasks activated by the TCAM dispatcher. One 
four-word entry is created for each subtask activated. When the end of the table is reached, 
the table is wrapped around; new entries overlay the oldest entries. Maximum to be 
specified is 65535: If 0 is specified, the table is not generated. 


OLTEST=number 
O = number 


Specifies the number of 1024 byte blocks to be used for Online Test procedures. This 
parameter corresponds to the OLTEST parameter of the TSOMCP macro instruction. The 
default is 0, which indicates that Online Test will not be used. The value must be O or an 
integer greater than 9 and less than 256. For a system with display stations the minimum 
value is 14 rather than 10. 


CIB = integer 
C = integer 


Specifies the maximum number of Command Input Blocks (CIB) that can be used at any 
one time in the TCAM subsystem. CIB’s are the buffers used to contain operator control 
messages entered at the system console. The maximum that can be specified is 255. If the 
operand is omitted, ‘“CIB=2”’ is assumed. At least two CIB’s should be specified, since 
START uses one. If an attempt is made to enter an operator control message from the 
system console, and the number of CIB’s specified is already in use, the message is rejected 
by TCAM. 

Figures 16, 17, and 18 show the MCP macro specifications for three sample systems. 


The first system, shown in Figure 16, has: 


1. 


10 lines for leased, (non-switched), 2741’s; all are BCD terminals and use EBCDIC character set 
only. All terminals in this line group have both Receive and Transmit Interrupt features. 


. 5 lines of teletype (which could be either 33 or 35). 


. The system operator will be prompted to enter TCAM parameters when he starts TCAM. At that 


time he can override any of the parameters specified on the TSOMCP macro as well as TCAM 
parameters. See the description of the TSOMCP macro instruction, for parameters pertinent to 
TSO. (The operator will always have to reply “‘s=c,u”’ STARTUP=COLD and a “‘u” to 
terminate prompting.) A Dispatcher Subtask Trace Table, useful for debugging purposes, is to be 
included in the MCP. It will contain 100 4 byte entries. (DTRACE=100) 


The sample system shown in Figure 17 has 10 dial lines, to be used by both 1050’s and 2741’s. The 
station identification character for the 1050’s is ‘‘A’’. Notice that it is specified in terminal 
transmission code, (E2) not EBCDIC (C1). Assume there are four types of terminals in the line 
group. 


A. Three 1050’s, with Text Timeout Suppression feature and Receive and Transmit Interrupt 


features. 
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B. One 1050, with Text Timeout Suppression feature. 

C. Five 2741’s, with Correspondence Code, Receive and Transmit Interrupt features. 
D. Two 2741’s, with EBCDIC code. 

The default is ATTN and NOBREAK. 


Users at terminals in groups A and C could use the TERMINAL command to request Transmit 
Interrupt handling, (BREAK) or the installation could provide a special LOGON cataloged 
procedure for these users containing a suitable interruption during output, or while the keyboard is 
locked, or after a number of consecutive lines of output, when output is being sent. This also could 
be specified in a LOGON procedure. 


LINEGRP TERM=2741,DDNAME=LNGP2741,LINENO=10, 
TRANTAB=EB41 ,DIAL=NO 


LINEGRP TERM=3335,DDNAME=LNGPTWX, LINENO=5 
TSOMCP OPTIONS=PROMPT, DTRACE=100 





Figure 16. Sample MCP 


LINEGRP TERM=5041,DDNAME=DIAL5041,LINENO=10,ADDR=E2, 
FEATURE=TOSUPPR 
TSOMCP 





Figure 17. Sample MCP 


The sample system shown in Figure 18 has one line group with two lines. These lines are connected 
to 3270 display systems operating in ASCII transmission code. The first line is connected to one 
control unit with four display stations. The second line is connected to one control unit with two 
display stations. The first line has control unit number O and device numbers 0, 1, 2, and 3. The 
second line has control unit number 1 with device numbers 4 and 5. 


LINEGRP TERM=327R,DDNAME=ANR, LINENO=2, 
DIAL=NO, TRANTAB=ASCI , TERMNO=( 4, 2 ) 
LISTTA RLN=1 , ADDR=( 2020, 2041, 2042, 2043 ) 


LISTTA RLN=2 , ADDR=(4144,4145) 
TSOMCP 


Figure 18. Sample MCP 





Writing Cataloged Procedures for TSO 


Two categories of cataloged procedures are used by TSO. The first includes procedures invoked by 
the system operator when he starts any of these four TSO tasks: 


1. The Message Control Program (MCP). 
. The Time Sharing Control Task (TSO). 
. The Background Reader for the SUBMIT command (BRDR). 


> wo WN 


. The TSO Trace Writer. 


The second category consists of those procedures invoked each time a LOGON command is 
entered at a terminal. The PROC operand of the LOGON command specifies the name of the 
cataloged procedure which: 
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1. Contains the JCL statements that define the data sets available to the terminal user. 


2. Specifies the name of the Terminal Monitor Program (TMP) supplied with TSO or the 
user-written substitute for the TMP. 


Both categories of cataloged procedures must be members of SYS1.PROCLIB or members of 
dedicated partitioned data sets. 


Message Control Program 


The cataloged procedure used to start the Message Control Program specifies through the P@M= 
operand of the EXEC statement the MCP to be started. The MCP should be named IEDQTCAM. 
This name allows the MCP to run in a region smaller than MINPART and ensure that the MCP can 
not be canceled, that is the operator must halt it. Specify ROLL=(NO,NO) to preclude an attempt 
to Rollout the MCP. Specify DPRTY=(15,15) to insure high priority. The MCP must run at a 
higher priority than the TSC. 


The cataloged procedure used to start the MCP also must define any terminals attached to the 
system as data sets. This is done through the ddnames specified in the LINEGRP macro instructions 
used in generating the MCP. Figure 19 shows two procedures that can be used to start the two 
sample MCPs generated in Figure 16 and 17. 


//MCP1 EXEC PGM=IEDQTCAM,ROLL=(NO,NO),TIME=1440,DPRTY=(15,15), X 
REGION=70K 
JTINGRO TA) UNIT=021 FIRST LINE GROUP DATA SET 2741 
UNIT=022 
UNIT=023 
UNIT=024 
UNIT=025 
UNIT=026 
UNIT=027 
UNIT=028 
UNIT=029 
UNIT=02A 
UNIT=02B SECOND LINE GROUP DATA SET TWX 
UNIT=02C 
UNIT=02D 
UNIT=02E 
UNIT=02F 


//MCP2 EXEC  PGM=IEDQTCAM, ROLL=(NO,NO), TIME=1440,DPRTY=(15,15), X 
REGION=66K 
//DIAL5041 UNIT=021 LINE GROUP DATA SET 
UNIT=022 
UNIT=023 
UNIT=024 
UNIT=025 
UNI T=026 
UNIT=027 
UNIT=028 
UNIT=029 
UNIT=02A 





Figure 19. Sample MCP Start Procedures 
Time Sharing Control Task 
The cataloged procedure used to start the Time Sharing Control Task contains the Job Control 


statements defining all the system resources the TSC requires. The procedure consists of an EXEC 
statement and several Data Definition statements. 
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The EXEC statement of the cataloged procedure that starts the Time Sharing Control Task, 
specifies: 


e The TSC program name, which is IKJEATOO. 


e« The TSC region size. This size can be overridden (1) by the TSCREGSZ parameter of the TSO 
Start parameters in SYS1.PARMLIB, (2) by the operator on the START command, or (3) by the 
TSC initialization routines if a larger region is required. If the size specified is less than the 
MINPART defined for the installation, it must be greater than or equal to the Time Sharing 
Control region size. Refer to IBM System/360 Operating System: Storage Estimates, GC28-6551, 
for how to calculate the Time Sharing Control region size. 


e ROLL=(NO,NO) to preclude an attempt to roll out the TSC region, if OPTIONS=ROLLOUT 
has been specified during system generation. 


e DPRTY= to set a priority for the TSC. It must be lower than the MCP. 
Five data sets must be defined. 


e SYSPARM -- The library containing TSC initialization parameters. These parameters are 
discussed under ““TSO System Parameters’’. 


« SYSUADS -- The User Attributes Data Set; this data set cannot be concatenated. 


e SYSLBC -- The broadcast data set which contains messages for users. In addition, the broadcast 
data set contains a list of valid users, generated by the ACCOUNT command and its 
subcommands. 


e SYSWAPOO -- The swap data sets. 


« IEFPDSI -- The partitioned data set containing LOGON cataloged procedures. This data set may 
be either SYS1.PROCLIB or a partitioned data set dedicated to LOGON procedures. A dedicated 
data set will speed up LOGON processing. 


For each of these data set definitions, DISP=SHR should be specified. 


Parallel units must be of the same device type. A swap data set must be allocated in cylinder 
multiples on a cylinder boundary. 


If an installation uses the TSO dump, SYSTSDP, the TSO dump data set, usually a tape volume, 
should be defined. 


Figure 20 shows a sample cataloged procedure to start the TSC. 


/ /LEFPROC EXEC PGM=IKJEATOO , ROLL=(NO,NO),DPRTY=(13,13) 
//SYSPARM DSN=SYS1.PARMLIB,DISP=SHR 

//SYSUADS DSN=SYS1.UADS,DISP=SHR 

//SYSLBC DSN=SYS1.BRODCAST DISP=SHR 


//SYSWAPOO DSN=SYS1.SWAP1,DISP=SHR 

//SYSWAPO1 DSN=SYS1.SWAP2,DISP=SHR 

//TEFPDSI DSN=SYS1.PROCLIB, DISP=SHR 

//SYSTSDP UNIT=2400 , VOL=SER=TSODUMP, DISP=( , KEEP ) 





Figure 20. Sample Cataloged Procedure to Start Time Sharing Control Task 


The data definition ddname on the DD statement defining the SWAP data set specifies whether 
serial or parallel swapping is to be used. The ddname is of the form: 


SYSWAPIn 


74 TSO Guide (Release 21.7) 


where | indicates the level of the data set, i.e., 0 for prime, 1 for first overflow; and n is the data set 
number at this level. 


For example, if an installation has two data sets and wants to use parallel swapping it would use 
SYSWAPO0O0 and SYSWAPO1 as the ddnames. 


If an installation wanted to use a IBM 2301 drum for a prime swap data set and a IBM 2314 as 
overflow, the ddnames would be SYSWAPO0 for the 2301 the prime data set, and SYSWAP10 for 
the 2314, the first overflow data set. 


If a system or TSO failure causes TSO to be restarted, you can use IMDPRDMP program to save 
the swap data sets before attempting to restart TSO. When invoking IMDPRDMP, the DD 
statements for the swap data sets should be the same as those in the TSO cataloged procedure; the 
//PRINTER DD statement writes to tape with chained scheduling and a large blocking factor so 
that the data sets are dumped quickly. The publication IBM System/360 Operation System: Service 
Aids, GC28-6719 shows the procedures for analyzing system failures and how to use the 
IMDPRDMP program to save the swap data sets. 


Starting and Stopping TSO: 
When the operator starts TSO for the day, he must: 


1. Issue a START command to start the Message Control Program. The operand of the START 
command is the name of the cataloged procedure that provides the Job Control statements 
necessary to execute the MCP. For example if the cataloged procedure used to start the MCP is 
named TCAM, the operator will issue a START TCAM command. 


2. Issue a START command to start the Time Sharing Control Task (TSC). The operand of this 
command names a cataloged procedure used to start the TSC. For example if the cataloged 
procedure used to start the TSC is name TS, the operator would issue a START TS command. 


When the operator stops TSO for the day, he must: 


1. Issue a STOP command to stop the Time Sharing Control Task. The operand of the STOP 
command must be the same as the operand that was used to start the TSC. 


2. Issue a HALT command to stop the Message Control Program. If the PGM= operand of the 
EXEC statement in the cataloged procedure used to start the MCP is IEDQTCAM, then the 
MCP cannot be cancelled with a CANCEL command. If the operator cancels the MCP, the TSC 
must be stopped before the MCP is restarted. The MCP cannot be halted with a HALT 
command unless TSO is stopped. 


Defining a UADS using the TSC Procedure: 


When a TSO system is first started after system generation, it is necessary to construct a UADS 
using the ACCOUNT command. The distributed UADS contains one valid user: IBMUSER and this 
user is authorized to use one procedure: IKJACCNT. The installation manager should use the 
ALLOCATE command to define a new UADS with a file name of SYSUADS and a data set name 
other than SYS1.UADS, specifying a volume serial number. The installation manager should then 
define its UADS structure with a series of ACCOUNT command ADD subcommands. He should 
then log off, stop the system, and change the SYSUADS DD statement in the TSC start procedure, 
to point to the new UADS. 


Note: The ACCOUNT command subcommands in addition to changing the UADS, also maintain a 
list of valid userids in the Broadcast data set. This list is checked by the SEND command before any 
messages are sent. If an installation generates a new TSO system and saves the old UADS, it must 
also save the old Broadcast Data Set. 
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Background Reader (BRDR) 


The cataloged procedure used to start the Background Reader (BRDR) contains Job Control 
statements that: 


e Specify the program name of the Background Reader. 
e Pass the Background Reader standard Reader-Interpreter parameters. 
e Define required data sets. 


The Background Reader, (BRDR), runs as a system task. It is started by the operator. It 
interprets Job Control Language passed by a terminal user with the SUBMIT command. If there is 
no input for the BRDR, it will relinquish its region and wait for input. Output from the BRDR is 
placed on SYS1.SYSJOBQE and is queued for execution by a standard initiator. The cataloged 
procedure that provides the Job Control Language to start the Background Reader is similar to 
other reader procedures. The BRDR program name is IKJEFF40. Figure 21 shows an example of a 
BRDR procedure. For further information on writing system reader/interpreter cataloged 
procedures, see IBM System/360 Operating System: MVT Guide, GC28-6720. 


An installation exit can gain access to and modify or delete any JCL passed by the SUBMIT 
command processor. The section, ‘‘Writing Installation Exits for the SUBMIT Command” describes 
how to write this exit. 


/ /BRDR EXEC PGM=IKJEFF4O, 
REGION=70K, 
PARM='Reader/Interpreter Parameters' 
DSN=SYS1.PROCLIB, 
DISP=SHR 


UNIT=SYSDA, 
SPACE= (80,(500,50),RLSE,CONTIG), 
DCB=( BUFNO=2 , LRECL=80 , BLKSIZE=80 , DSORG=PS, 
RECFM=F , BUFL=80 ) 
//TEFRDER DD DUMMY 





Figure 21. Sample Background Reader (BRDR) Procedure 
TSO Trace Writer 


Ths TSO Trace Writer collects Time Sharing Driver Entry Codes and writes them out to a data set. 
The Trace Writer operates in its own partition and is started by the operator. A cataloged procedure 
distributed with TSO defines the resources needed to run TSO Trace. 


The cataloged procedure used to start the TSO Trace Writer: 


« Specifies the program name of the TSO Trace facility. 
e Passes to the Trace Writer a parameter which controls sampling rate. 
* Defines the TSO Trace output data set. 


Figure 22 shows the procedure. The sample procedure specifies that the Trace Writer output data 
set is to be written to a 2400 tape unit. The output data set can also reside on disk. The user may 
specify that chained scheduling be used if trace data set is on tape. If an installation specifies in the 
DCB operand of the DD statement an NCP value, it must be at least three, that is, 


DCB=( BLKSIZE=&BLKSIZE,NCP=3 ). 


An installation should not include a SYSABEND or SYSUDUMP statement in the TSO TRACE 
cataloged procedure. 
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//TXTRACE PROC TRREGN=20K, DEFAULTS: REGION SIZE=20K 
TRPARM=100, ENTRY RATE=100 ENTRIES/SEC 
VOLCNT=20, VOLUME COUNT=20 
BLKSIZE=2048 BUFFER SIZE=2048 

//* DESCRIPTION OF SYMBOLIC PARAMETERS --- 

//* TRREGN - TRACE WRITER REGION SIZE 

//* TRPARM - AN ESTIMATE OF THE RATE AT WHICH ENTRIES WILL BE MADE 

//* INTO TRACE BUFFERS IN NUMBER OF ENTRIES PER SECONDS 

//* VOLCNT - MAXIMUM NO. OF VOLUMES AVAILABLE FOR TRACE DATA SET 

//* PER RUN. MAXIMUM VALUE ALLOWED IS 255. 

//* BLKSIZE - SIZE OF TRACE BUFFERS. MINIMUM SIZE ALLOWED BY TRACE 

//* WRITER IS 128; MAXIMUM ALLOWED BY SYSTEM IS 32,760 

//* 

//YTEFPROC EXEC PGM=IKJFATRC, INVOKES INITIALIZATION MODULE 
DPRTY=14, PRIORITY SHOULD AT LEAST BE HIGHER 
REGION=&TRREGN, THAN CPU-BOUND JOBS IN THE SYSTEM 
PARM= &TRPARM 


DSNAME=TSTRACE, NAME OF TRACE DATA SET 

UNIT=2400 DATA SET CREATED ON 9-TRK TAPE(s ) 
DISP=(NEW,KEEP ), 

DCB=( BLKSIZE=§&BLKSIZE), 

VOLUME=( , , , &VOLCNT ) 





Figure 22. Sample TSO Trace Start Procedure 
Logon Cataloged Procedure 


The LOGON cataloged procedure defines the system resources that the terminal user can use. The 
LOGON cataloged procedure can be named in the PROC operand of the LOGON command or 
supplied through an installation exit from the LOGON processor. This procedure: 


e Defines or allows for dynamic allocation of all data sets used by the terminal user. 


e Specifies which program is to be invoked after LOGON, the TMP distributed with TSO or a user 
written program. 


The data sets defined can include the common system utility data sets, and data sets used by the 
compilers such as SYSUT1, SYSUT2 or even the specialized data sets used by the Assembler or the 
Linkage Editor. 


In addition any data sets that will be allocated through the ALLOCATE command must have a 
corresponding DD DYNAM statement. Any data sets needed by a processing program such as a 
compiler or a system utility can be defined dynamically through the ALLOCATE command or through 
Dynamic Allocation. 


The Terminal Monitor Program distributed with TSO is named IKJEFTO1. If a user written TMP is 
to be used for a particular procedure, then its module name should be substituted for IKJEFTO1 in the 
PGM-=operand on the EXEC statement. 


The PARM operand on the EXEC statement is interpreted by the Terminal Monitor Program 
(TMP) as the first line of input from the terminal. 


ROLL=(NO,NO) should be specified to preclude rolling out the Time Sharing Region. 
REGION = is ignored 


The command library, SYS1.CMDLIB, contains the command processor load modules. An 
installation can also load many of these modules into the TSO Link Pack Area. The command library 
can be concatenated to SYS1.LINKLIB or defined in the LOGON procedure as a step library. 
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Note: If the command library is defined in the LOGON procedure as a step library, the modules in 
the TSO Link Pack Area will not be used. This will degrade performance. 


To concatenate SYS1.CMDLIB to SYS1.LINKLIB, use the LNKLSTO00O member of 
SYS1.PARMLIB. See IBM System/360 Operating System: MVT Guide, GC28-6720 for further 
information about using LNKLSTOO. 


Figure 23 shows an example of a LOGON procedure. 


The sample LOGON procedure can be useful to a programmer using COBOL. Statement 1 
specifies the TSO standard TMP for execution. Statement 2 defines the data set containing the 
HELP command messages. Stafqment 3 defines a utility data set used by several command 
processors while statement 4 defines the EDIT utility data set. Statements 5, 6, and 7 define utility 
data sets used by the COBOL compiler. Statement 8 defines the COBOL subroutine library. 
Statements 11 through 17 define data sets which can be allocated during the terminal session by the 
user or a program he invokes, using the ALLOCATE command. Statement 18 defines SYSPROC, 
an installation defined partitioned data set containing command procedures. 


//COPROC EXEC PGM=IKJEFTO1,ROLL=(NO,NO) 

//SYSHELP DD DSN=SYS1.HELP,DISP=SHR 

//SYSUT1 DD DSN=E8SYSUT1, UNIT=SYSDA , SPACE=( CYL, (10,10)) 
//SYSEDIT DD DSN=EEDIT, UNIT=SYSDA, SPACE=( 1688,(50,20)) 
//SYSUT2 DD DSN=ESYSUT2, UNIT=SYSDA, SPACE=( TRK,(10,5)) 
//SYSUT3 DD DSN=ESYSUT3, UNIT=SYSDA , SPACE=( TRK,(10,5)) 
//SYSUT4 DD DSN=ESYSUT4, UNIT=SYSDA, SPACE=( TRK,(10,5)) 
//SXSLIB DD DSN=SYS1.COBLIB, DISP=SHR 

//SYSIN DD TERM=TS 

//SYSPRINT DEC TERM=TS 

//DD1 DD DYNAM 

//DD2 DD DYNAM 

//DD3 DD DYNAM 

/,/DD4 DD DYNAM 

//DDS5 DD DYNAM 

/ /DD6 DD DYNAM 

//DD7 DD DYNAM 

//SYSPROC DD DSN=CMDPROC,DISP=SHR 





Figure 23. Sample LOGON Cataloged Procedure 
TSO System Parameters 


When the Time Sharing Control Task initializes the TSO system, it reads a series of parameters 
from a member of the partitioned data set named on the SYSPARM DD statement. The SYSPARM 
DD statement appears in the cataloged procedure used to start the TSC. The member name is 
IKJPRMOO or a name supplied by the operator on the START command. There are three types of 
parameters. 


e TSC parameters. 
¢« Time Sharing Driver parameters. 
e Parameters dealing with the allocation of terminal buffers. 


All of these parameters have an effect on the size of the TSC region. The publication IBM 
System/360 Operating System: Storage Estimates, GC28-6551 gives formulas for assessing the effects 
of these parameters on region size. 
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The Time Sharing Control Task Parameters 


The TSC parameters: 


¢ Define the number and size of the Time Sharing regions. 

e Optionally specify a size for the TSC region. 

e Specify the maximum number of users. 

e Specify whether SMF is to be used. 

e Specify which DRIVER to use. 

¢ Limit the number of tracks the SUBMIT command can use to queue jobs. 
¢ Define the module contents of the Time Sharing Link Pack Extension. 


Notes: 


e All parameters except LPA and DUMP/NODUMP may be overridden on the START command. 
e USERS, SMF, REGSIZE(n), and SUBMIT may be changed by a MODIFY command. 


e TERMAX, REGNMAX, and MAP must be specified either in SYS1.PARMLIB or on the 
START command used to start TSO. 


The contents of the Time Sharing Link Pack Area, that part of the TSC region containing 
reenterable modules common to different TSO applications has a direct effect on system response 
and overhead. The following routines are used by different users many times during an average 
session and should reduce loading time if included. 


e The I/O Service routines -- that is GETLINE, PUTLINE, PUTGET, and STACK. 
e The TMP mainline routines. 

e Command Scan -- a service routine used to check the syntax of commands. 

e TIME -- a routine used to get the time of day. 

e PARSE -- a routine that analyzes the syntax of commands. 


In addition if EDIT is being used extensively, portions of the EDIT command processor should be 
included. 


e The Edit Mainline routines. 

e INPUT subcommand processor. 

e LIST subcommand processor. 

e CHANGE subcommand processor. 

e Implicit change processor, that is , the update function for portions individual lines. 


Driver Parameters 


The DRIVER parameters define dispatching and swap scheduling algorithms (1) for user jobs within 
one time sharing region and (2) between two time sharing regions. 


The DRIVER parameters dealing with activity within each region determine: 
e The type of swap scheduling to be used, preemptive or round robin. 
e The number of service queues in a region. 


e The cutoff points for each queue in terms of swapload or main storage residence between 
interactions (terminal I/O requests). 


e The algorithms used to calculate time slices for each queue. 


Preparing a System for TSO 79 


Certain parameters apply to service queues and require queues to be defined through the 
SUBQUEUES parameter. These parameters usually are used in pairs, one parameter specifying that 
a certain criterion is to be used in queue placement and the other specifying the value to be used. 


For example, the SWAPLOAD/NOSWAPLOAD parameter specifies whether or not swap load 
will be used as a criterion for determining which queue a user will be put in. If SWAPLOAD has 
been specified, the MAXSWAP parameter defines the maximum swap load for each queue. 


These paired parameters dealing with service queues are: 
SWAPLOAD/MAXSWAP(n,m) =iii 
AVGSERVICE/SERVICE(n,m) =iii 

OCCUPANCY /MAXOCCUPANCY (n,m) =iii 


Note: ‘n’, ‘m’, and ‘iii’ refer to region number, queue number and a value associated with the 
parameter, such as k byte blocks for SWAPLOAD. 


The DRIVER parameters dealing with activity between time sharing regions determine: 
e Whether new users are to be assigned to a region based on region activity. 


e« What type of dispatching the Driver uses between multiple regions or between foreground and 
background tasks. 


There are three types of dispatching: (1) Simple, (2) Even, and (3) Weighted. The parameters 
involved are PRIORITY, WAIT and BACKGROUND. 


If an installation specifies NOPRIORITY and NOWAIT, then simple dispatching is used. The 
formula used is: 


MS = AT 


where MS is the minor time slice and AT is the available execution time, or the time remaining 
before the next scheduled swap out. 


If an installation specifies PRIORITY and NOWAIT, then even dispatching is used. The formula 
used is: 


AT 
MS =N 


where N is the number of foreground regions containing jobs ready to execute. As in simple 
dispatching, available time is reduced before the calculation by any guaranteed background 
percentage. 


If an installation specifies PRIORITY and WAIT, then weighted dispatching is used. The formula 
used is: 


This job's EWTS% 
Sum of EWT%s 


where MS is the minor slice to be assigned to a terminal job, EWT% is the estimated wait time 
percentage, and AT is the available execution time for this minor slice cycle, again adjusted for any 
guaranteed background percentage. 


In a single region system, NOWAIT, NOACTIVITY, and NOPRIORITY should be specified. 
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th. 


The decay constants for the wait estimate (DECAYWAIT) and the activity estimate 
(DECAYACT) are used to smooth out excessive variations in activity and I/O wait time. If a value 
of 100, a decay constant of one since the value is in hundredths is used, the current value has a 
weight equal to the old value. If a value less than 100 is used, the current value has the most 
weight. If a value greater than 100 is used, the old value has the most weight and will “smooth out” 
the effects of excessive variations. 


The expression used is: 


new-value = (old-value x decay-constant) + current-value 
(decay-constant + 1) 


MINSLICE, the minimum amount of residence time (major time slice) given to a user program 
on a given service queue, should be set to allow a useful amount of execution time. One way to 
calculate MINSLICE is to divide the acceptable response time by the assumed average number of 
users for a normal load. 


If AVGSERVICE has been specified, then the major time slice for users on a given queue is 
calculated each time the queue is serviced. The value specified by SERVICE for that queue is 
divided by the number of ready users and the result is compared to the MINSLICE value. The 
higher of the two is used as the major time slice. 


This means that with a normal number of users active, each user program will receive a major 
time slice at least equal to the MINSLICE value, with a given average response. As the number of 
users drops, the average response time will remain the same but each user program will receive a 
longer time slice, based on the SERVICE value. 


If PREEMPT is specified, CYCLES should be set to zero, since a higher priority queue will 
preempt a lower priority queue. 


The system operator is prompted for all necessary values that are not specified. For example if 
OCCUPANCY has been specified, but no MAXOCCUPANCY values entered, the system operator 
will have to supply values for each service queue in each region. At least one service queue must be 
defined for each region, and a CYCLES value specified for all service queues defined to preclude 
unnecessary prompting. 


If a parameter is specified or entered incorrectly, the parameter is ignored, but no error message 
is issued. 


Buffer Control Parameters 


TSO controls the allocation of terminal buffers in the TSC region. Buffer allocations are based on 
initial parameters specified in SYS1.PARMLIB. 


The BUFSIZE= parameter specifies the size in bytes of each TSO terminal buffer. 


The BUFFERS= parameter specifies the total number of TSO buffers. The remaining parameters 
deal with allocating the number of buffers per user when a given number of users is logged on. 


TSO maintains a count of the number of allocated buffers per user, both for input and output. 
When the number of buffers either for input or output rises to a given level, the user is prevented 
from continuing until more buffers are available. If the specified maximum number of input buffers 
are allocated, the keyboard is locked up. If the maximum number of output buffers are allocated, 
the user’s program is put into a wait. This level is determined by the OWAITHI value for output 
and the INLOCKHI value for input. 
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When the number of logged on users changes by the percentage specified in the USRCHGE 
parameter, and when the number of users falls below SLACK value, the number of buffers per user 


is readjusted. The number of buffers for input and output are distributed in the same ratio as 
specified by INLOCKHI and OWAITHI. 


System Parameter Format 


The format of the parameter records is: 
6 6 parameter-owner b keyword=value Bb... 
where 6 stands for one or more blanks. 
The possible parameter-owners are: 
¢ TS -- parameters for the Time Sharing Control Task. 
e DRIVER -- parameters for the Time Sharing Driver. 
e TIOC -- parameters controlling terminal buffer allocation. 
Keywords cannot be continued but may be repeated. This has the effect of continuation, as repeated 
keyword values are added on to those already specified. When two parameters conflict, the last 


value is used. Figure 25 shows an example of system parameters for a single region model 50 and 
for a double region model 65. Figure 24 shows the syntax and meaning of the start parameters. 
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PARAMETER KEYWORD MEANING 
OWNER 


TS TERMAX=nnnn Specifies maximum number of users. 


USERS=nnnn Specifies initial maximum number of users, defaults to 
TERMAX, can be changed by MODIFY command. 


REGNMAX=nn Specifies number of TSO user regions. 


MAP=nn Specifies the number of MAP entries, used to reduce 
swapping of unused storage. 


OFF 
SMF=[ | OPT=1 EXT= |YES Standard SMF parameters; see System Management 
OPT=2 NO Facilities, GC28-6712. The default is the same as 
the default defined for the background region. If no 
background default exists, the default is OPT=2 
and EXT=YES. 


DSPCH=cccccc Specifies first six characters of Time Sharing Driver. 
Defaults to IKJEAD, driver supplied with TSO. This 
parameter defines the names of all four Driver 
modules. That is the driver supplied with TSO has 
four modules, IKJEADOO to IKJEADO3. 


LPA=(module list) List of modules to be included in Time Sharing Link 
Pack Extension. 


REGSIZE( nn )=( mmK, Specifies region size (mmk) and LSQS size (iiik) 
111K) for region nn. Defaults to zero. 


SUBMIT=nnnn Specifies the maximum number of tracks in the SUBMIT 
command job queue. Defaults to limit set at System 
Generation. 


TSCREGSZ=nnnnnk Specifies amount of main storage to be allocated to 
Time Sharing Control Task region. mnnnnn is number of 
contiguous 1024 byte areas desired, must be even, and 
May not be more than 16382. An odd number will be 
rounded up to next higher even number. If not 
specified in either SYS1.PARMLIB or in START command, 
Time Sharing Control Task will calculate its own 
region size. 


DUMP=§ DUMP DUMP indicates that swap units are to be marked 
NODUMP reserved. Necessary if a SWAP dump to be taken. 


TIOC BUFSIZE=nn Specifies size of terminal buffer. Default 44. 
BUFFERS=nn Total number of buffers. 


OWAITHI=nn Specifies the maximum number of allocated output 
terminal buffers per user in order to put a user 
program into output wait. 


INLOCKHI=nn Specifies the maximum number of allocated input 
terminal buffers per user in order to lock a users 
keyboard. 

OWALTLO=nn Specifies the number of allocated output buffers to 


bring a user out of output wait state. In other words 
if OWAITLO=4, when 4 or less buffers remain allocated, 
the user is brought out of output wait. 


INLOCKLO=nn Specifies the number of currently allocated input 
buffers to unlock the terminal keyboard for input. In 
other words, when the number of allocated input 
buffers fail to or below the INLOCKLO value, the 
users's keyboard is unlocked. 


Figure 24. TSO System Parameter Syntax (Part 1 of 4) 
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USERCHG=nn 


RESVBUF=nn 


SLACK=nn 


PARAMETER 


ACTIVITY 


AVGSERVICE 


BACKGROUND=nn 


CYCLES(n,m)=1111 


DECAY ACT=nnnn 


DECAYWAIT=nnnn 


Specifies percentage of change in logged on users 
needed to redistribute buffers and recalculate the 
OWAITHI and INLOCKHI numbers during slack time. 


Specifies the total number of terminal buffers that 
must be free to avoid locking all terminals to prevent 


input. 


Specifies number of logged on users that constitute 


slack time. 
DRIVER PARAMETERS 
EFFECT 


Use average region activity in 
selecting a region for a new user. 
Single region systems should specify 
NOACTIVITY. 


Calculate major time slice for users 
on a queue by dividing number of 
ready users by value set in SERVICE. 


The specified percentage of available 
CPU time is guaranteed for background 
(non-TSO) tasks. 


The number of times an entire queue 
will be serviced (ie. each ready 
user swapped in before the next 
lower queue is serviced.) If zero 
1s specified; the queve 1S serviced 
until empty, (no ready users) 
Cycles must be specified for each 
region. 


The specified exponential decay con- 
stant (in 1/100ths) will be used to 
smooth average region activity. 
Higher values make history more 
important. 


The specified exponential decay 
constant (in 1/100ths) will be 
used to smooth average I/O wait 


time. Higher values make history 
more important. 


Figure 24. TSO System Parameter Syntax (Part 2 of 4) 
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OPERAND 


none 


nn 
percentage 


n 
region 
m 
service 
queue 
111 
cycles 


nnn 
exponential 
decay constant 
in 1/100ths. 
Value of 100 
makes history 
as important 
as current 
value. 


nnn 
exponential 
decay constant 
in 1/100ths. 
Value of 100 
makes history 
as important 
as current 
value. 





PARAMETER EFFECT 


MAXSWAP(n,m)=11i1 A user maximum swap load for queue 
m in region n is iiii 1024 byte 
blocks. A user exceeding this 
swap load will be moved to 
a lower priority queue. 


MAXOCCUPANCY(n,m)=111i1 Occupancy is the accumulated time 
a user has resided in main storage 
Since the last terminal interaction. 
If a user on queue n in region n, 
accumulates more than iiii 1/100ths 
of a second of occupancy, he will be 
moved to a lower queue. 


MINSLICE(n,m)=11i11 The minimum amount of core residency 
allotted to a user on queue m in 
region n is 1111 (1/100ths) of a 
second. 


NOACTIVITY Region activity average will not 
be used in aSSigning new users to 
regions. NOACTIVITY should be 
specified for single region 
systems. Default. 


NOAVGSERVICE AVGSERVICE calculations are not 
performed. Default. 
NOBACKGROUND Background tasks will not be 


guaranteed a minimum amount of 
execution time. Default. 


NOOCCUPANCY The length of time a user 
program is resident will not 
be used to position him ona 
service queue. Default. 


NOPREEMPT Preemptive swap scheduling is 
not used. Default. 

NOPRIORITY Minor time slices are not calculated 
Default. 

NOSWAPLOAD Swap load (size of programs) will 


not be criterion for service queue 
placement. Default. 


NOWAIT I/O WAIT time estimate will not 
be used in dispatching between 
multiple regions. Causes even 
dispatching between regions if 
PRIORITY was specified, simple 
dispatching if NOPRIORITY was 
specified. Should be specified 
for single region system. Default. 


Figure 24. TSO System Parameter Syntax (Part 3 of 4) 


OPERAND 


n 
region 
m 
service queue 
Lill 
1024 byte 
blocks of 
swap load. 


n 
region 
m 
service queue 
1ilil 
1/100ths 
seconds. 


n 
region 
m 
service queue 
1iii 
1/100ths 
seconds. 


none 


none 


none 


none 


none 


none 


none 


none 
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EFFECT 


OCCUPANCY Residence times since last 
terminal I/O interaction are 
accumulated for current user 
program to use for service 
queue placement. 


PREEMPT Preemptive swap scheduling is 
used. Assumes multiple service 
queues defined through SUBQUEUES 
parameter. A user who comes ready 
on a higher queue preempts a 
resident user on a lower queue. 
The preempted user is Swapped out 
after a minslice of the preemptor 
has elapsed. The preemptors entire 
queue is serviced. 


PRIORITY If NOWAIT was specified, each 
region receives an equal minor 
time slice. If WAIT was specified, 
regions receive minor time slices 
based on I/O WAIT time. 


SERVICE(n,m)=1111 The amount of time (iiii 1/100ths n 
of seconds) is divided by the version 
number of ready users in queue m 
m, region n. The result queue 
is compared with MINSLICE, and the 1111 
larger is used as the major time 1/100ths 
slice. This calculation is per- of seconds 
formed whenever a queue is to be 
cycled, (all the ready users swapped 
in). 


SUBQUEUES (n)=mmm The number of service queues in n 
region 'n' is ‘'m'. Lower service region 
queue numbers have higher priority. Tamm 
If only one service queue is number of 
defined, then round robin swap service queues 
scheduling is used. At least one 
service queue must be defined for 
each region. 


Swap load or size of program 
in 1024 byte blocks, is used for 
queue placement. 


Causes I/O wait time estimate to 
be calculated for region. Used 
with weighted dispatching. 





Figure 24. TSO system Parameter Syntax (Part 4 of 4) 
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TS TERMAX=10 REGNMAX=1 REGSIZE( 1 )=( 100K, 8K) 
TS LPA=(IKJPTGT, IKJSCAN, IKJEFTO2,IKJEFT25 ) 
TS LPA=(IKJPARS ) 


DRIVER AVGSERVICE PREEMPT SUBQUEUES( 1 )=3 

DRIVER CYCLES( 1,1 )=0 

DRIVER CYCLES( 1,2 )=0 

DRIVER CYCLES( 1,3 )=0 

DRIVER MAXOCCUPANCY(1,1)=750 MINSLICE( 1,1 )=150 
DRIVER MAXOCCUPANCY(1,2)=1500 MINSLICE( 1,2 )=750 
DRIVER MAXOCCUPANCY( 1,3 )=4500 MINSLICE(1,3 )=4500 
DRIVER SERVICE(1,1)=150 

DRIVER SERVICE( 1,2 )=1500 

DRIVER SERVICE( 1,3 )=6000 

TIOC BUFSIZE=44 

TIOC BUFFERS=80 

TIOC OWAITHI=8 

TIOC OWAITHI=4 

TIOC INLOCKHI=4 

TIOC INLOCKLO=2 

TIOC SLACK=01 

TIOC RESVBUF=10 

TIOC USERCHG=99 

TS TERMAX=60 REGNMAX=2 REGSIZE(1)=100K,8K) REGSIZE( 2 )=( 100K, 8K) 
TS LPA=( IKJPTGT, IKJSCAN , IKJEFTO2,IKJEFT25 ) 

TS LPA=( IKJEBEM4 , IKJEBELP, IKJEBELT, IKJEBECH, IKJEBELI ) 
TS LPA=( IKJPARS ) 

DRIVER WAIT 

DRIVER PRIORITY 

DRIVER ACTIVITY 

DRIVER OCCUPANCY 

DRIVER AVGSERVICE 

DRIVER PREEMPT 

DRIVER DECAYWAIT=100 

DRIVER DECAYACT=100 

DRIVER SUBQUEUES( 1 )=3 SUBQUEUES( 2 )=3 

DRIVER CYCLES(1,1)=Q CYCLES(1,2)=0 CYCLES( 1,3 )=0 
DRIVER CYCLES(2,1)=0 CYCLES(2,2)=0 CYCLES( 2,3 )=0 
DRIVER MAXOCCUPANCY(1,1)=500 MINSLICE( 1,1 )=100 
DRIVER MAXOCCUPANCY (1,2 )=1000 MINSLICE( 1,2 )=500 
DRIVER MAXOCCUPANCY( 1,3 )=3000 MINSLICE( 1,3 )=3000 
DRIVER MAXOCCUPANCY(2,1)=500 MINSLICE( 2,1 )=100 
DRIVER MAXOCCUPANCY( 2,2 )=1000 MINSLICE( 2,2 )=5000 
DRIVER MAXOCCUPANCY(2,3)=3000 MINSLICE( 2,3 )=3000 
DRIVER SERVICE( 1,1 )=1000 

DRIVER SERVICE( 1,2 )=1000 

DRIVER SERVICE( 1,3 )=6000 

DRIVER SERVICE( 2,1 )=100 

DRIVER SERVICE( 2,2 )=1000 

DRIVER SERVICE( 2, 3 )=6000 


TIOC BUFSIZE=44 
TIOC BUFFERS=300 
TIOC OWAITHI=8 
TIOC OWAITLO=4 


TIOC 
TIOC 
TIOC 
TIOC 
TIOC 


Figure 25. Sample TSO System Parameters 


INLOCKHI=4 
INLOCKLO=2 
SLACK=12 

RESVBUF=60 
USERCHG=0 1 
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Tuning a System With TSO 


This section describes some techniques useful in improving the performance of a system with TSO. 
Some of these techniques act directly upon the underlying MVT control program, but they all affect 
TSO system performance. The specific objectives discussed are: 

¢ Reducing I/O contention between foreground (TSO) and background tasks. 


« Reducing time spent fetching modules. 


e Reducing swap overhead that is, the amount of I/O performed copying foreground job images 
between main and secondary storage. 


e Reducing seek time between different libraries and different parts of the same library. 


The techniques are discussed in terms of their objectives. Figure 26 summarizes the various techniques 
in terms of the times at which they are used. 


Writing 
LOGON 
Writing Procedures 
SYS1.PARMLIB Cataloged UADS Library 
SYSGEN Construction Procedures | Building Positioning 


Reducing UNITNAME 
Foreground/ IOREQUE=PRIORITY 
Background I/O 
Contention 


Reducing Operator Communications | BLDL (SVC) 
Fetch Time Residence Options BLDL (LINKLIB) 
Transient Area TSLPA 

LPA 





Reducing ABSTR (JCL) 
Seek Time ITEHDASDR (VTOC) 


TEBCOPY 
| 
Tuning the TSO TRACE 
Driver 


LEHMOVE 
Figure 26. Summary of Tuning Objectives for Various Techniques 














Reducing I/O Contention Between Foreground and Background 


To reduce the I/O contention between foreground (TSO) tasks and background tasks: 


1. During System Generation, use the UNITNAME macro instruction (1) to separate direct access 
space into foreground (TSO) and background areas and (2) to define generic names, unitmames, 


for these spaces. (IBM System/360 Operating System: System Generation, GC28-6554, discusses the 
UNITNAME macro instruction.) 


In cataloged procedures for background use, define utility data sets with the UNIT parameter 
specifying one of the background unitnames, (for example, SYSDA). 


In cataloged procedures for foreground use, notably the LOGON procedures, define utility data 


sets using a UNIT parameter specifying one of the foreground (TSO) unitnames, (for example, 
SYSTS). 
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Restrict placement of data sets allocated dynamically, (using the ALLOCATE command), by 
specifying a foreground unitname in the UADS. Define a unit for dynamically allocated data sets 
in the UADS with the ADD subcommand of the ACCOUNT command. 


Be sure to give the PUBLIC attribute, in the PRESRES member of SYS1.PARMLIB, to at least 
one of the Foreground Unitname volumes so that SYSOUT data sets will be dynamically 
allocated on a specific unit. See IBM System/360 Operating System: MVT Guide, GC28-6720, for 
more information on the PRESRES member of SYS1.PARMLIB. 


2. Specify priority scheduling on I/O for the direct access devices on which TSO data sets reside. 
Since foreground jobs usually run at higher priority than background jobs, this should reduce the 
time Foreground (TSO) jobs wait for background I/O requests. Use the IOREQUE operand of 
the IODEVICE macro instruction. For further information, see the System Generation publication. 


For an example of the use of UNITNAME, if your system has two 2314 Direct Access Storage 
Facilites available, at addresses 130 through 137 and 230 through 237, you could define generic 
names for scratch, utility, and spooling data sets by using the UNITNAME macro instructions 
specified in Figure 27. 


UNITNAME UNIT=(130,4),(230,4),NAME=SYSDA 


* BACKGROUND SCRATCH UNITNAME, NON-TSO 


UNITNAME UNIT=(134,4),(234,4),NAME=SYSTS 


* FOREGROUND TSO UNITNAME 





Figure 27. Sample Use of the UNITNAME Macro Instruction 


For the system in this example, if a data set is defined with a UNIT parameter specifying 
SYSDA, it will reside on one of the 2314 packs at addresses 130 to 133 or 230 to 233. Data sets 
defined with a UNIT parameter specifying SYSTS, will reside on one of the 2314 packs at addresses 
134, 135, 136, 137, 234, 235, 236, 237, or 237. 


There are advantages to using generic naming through the UNITNAME macro facility: 
1. There is no arm contention between foreground and background utility data sets. 
2. TSO utility data sets can be demounted easily when TSO is not active. 


If the UADS specifies that new dynamically allocated. data sets should reside on the units in the 
foreground unitname group, then there will be no arm contention between these data sets and 
background data sets. 


Reducing Fetch Time 


Reducing the time spent fetching modules from libraries is one of the most important controllable 
factors in system performance. For the purposes of this discussion, fetch time is defined as the time 
span from the start of execution of a macro instruction which obtains a module from secondary 
storage and optionally transfers control to the module to completion of this operation. Examples of 
these types of macro instructions are LINK and LOAD. 


Note: The following list of modules for residence and directory residence were selected based on a 
count of modules fetched during TSO operation. The modules are included because they fulfill at 
least one of the following criterion: 


e High fetch count. 
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e Reduce seek time between one or more of the following - SVCLIB, VTOC, or CATALOG. 
e Required for each line of terminal output. 

¢ Required for each line of terminal I/O. 

e Must be refreshed after SWAP-in if not resident. 

e Part of Catalog sequence. 

e BSAM CHECK routine for terminal I/O. 

e High use count for resident access modules. (Increases swap load if not resident.) 


If the referenced module is resident in the Link Pack Area, or the TSO Link Pack Area 
Extension, then no I/O is involved in a fetch. If the module is not resident, but if there is a BLDL 
entry for it, then a directory search is not required. If there is no BLDL entry, then I/O is required 
for the BLDL (directory search) and for the actual loading of the module. An installation therefore 
can influence fetch time through the following four options: 


1. SVC module residence. 


Figure 28 shows a list of SVC modules and their functions. For further information about loading 
modules into the Link Pack Area, see MVT Guide, GC28-6720. 


2. Resident directory entries (BLDL) for SVC library. 
The following Dynamic Allocation modules should be included in the SVC BLDL list: 


IGC0109I, IGC0209I, IGC03091, IGC07091, IGCO909I IGC10091, IGC1109I, IGC 12091, 
IGC1309I, 1GC14091, IGC14091, IGC15091, IGC16091, IGC17091, IGC26091, IGC2709I, 
IGC29091. 


The following Catalog Modules should be included in the SVC BLDL list: 
IGGOCLC2, IGGOCLC3, IGGOCLC7, IGGOCLF2. 
3. Resident directory entries (BLDL) for Linkage library, and TSO Command library. 


A LINKLIB BLDL entry in main storage occupies 56 bytes. Modules which have BLDL entries 
have their fetch time significantly reduced. For this reason, it is recommended that the entire list 
of modules in IBM System/360 Operating System: Storage Estimates, GC28-6551, listed under 
Reentrant Load Modules that can be made resident in the Time Sharing Link Pack Area,'’ be 
included in the Linkage Library BLDL list. 


4. SVC transient area pairs. 


In addition to defining module and directory (BLDL) residence, specifying during system 
generation two SVC transient areas for each initiator (background region) or each foreground 
region, decreases total time spent waiting for the loading of a non-resident SVC function. 


Module Name/Function 


IGCOO02F CATALOG 
ICGO002H OPEN Extent Catalog 
IGCOO0O03C I/O Halt 


IGCO006+ STAE 
IGC0009+4 XQMNGR 
IGCOO009C TGET/TPUT 
IGCOO09F STAX 
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IGCOO009G SVC 97 TEST 
IGCOOO09I SVC 99 Dynamic Allocation 
IGC25091 Dynamic Allocation Update DSE 


IGC25091 Dynamic Allocation Initiation 
IGGOCLC1 Catalog Locate 

IGGOCLC6 Catalog Return 

IGG09301 TPUT 


Figure 28. SVC Modules useful for Residence in TSO 





Reducing Swap Overhead 
There are two ways to reduce swap load: 


1. Use the MAP parameter of the TSC start parameters to reduce the amount of unused core 
swapped. MAP=6 is a recommended value. For further information about the MAP parameter, 
see ''TSO System Parameters." 


2. Any TSO modules resident in the TSLPA will not be swapped. This means that TSO modules 
common to foreground jobs, such as the TMP, should be considered for residency. 


Reducing Seek Time Between Different Libraries and Different Parts of the Same Library 


You can reduce seek time and increase I/O overlap by properly placing system data sets on direct 
access devices. 


Use the IEBCOPY utility program to move system data sets. Use the IEHMOVE utility program to 
move the system catalog. Use the IEHDASDR utility to place the VTOC of a volume. For further 
information about these utilities, see IBM System/360 Operating System; Utilities, GC28-6586. 


Use the ABSTR operand of the SPACE parameter on dd statements to position data sets. In 
arranging libraries on direct access devices, the following points should be kept in mind. 


1. Every reference to the system catalog requires a reference to the VTOC, since the catalog must 
be opened. If the system catalog and the VTOC share cylinders (split cylinders), then seek time 
is reduced. 


2. Unless the CATLG/UNCATLG modules (IGGOCLC2, IGGOCLC3, IGGOCLC7) are resident 
in the Link Pack Area, they must be fetched during any catalog operation. If these modules are 
not resident, it is useful to have the system catalog and SVCLIB adjacent on the storage device. 


3. To allow for maximum overlap during fetch 1/O, either CMDLIB or LINKLIB should reside on a 
different volume than SVCLIB. Since CMDLIB and LINKIB should be concatenated, they also 
should probably not reside on the same volume. 


4. In general, heavily referenced data sets, like LINKLIB and SYSJOBQE should be in proximity 
when they share a volume. 


The following example shows the dd statements used to define system data sets. The space 
parameters apply for 2314 volumes. It is assumed that the VTOC was placed on tracks 50 to 52 on 
these 2314 packs. Cataloging of data sets should be done after this allocation has been run. 
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//FORTLIB DSN=SYS1.FORTLIB, SPACE=( ABSTR,(28,2,40)),UNIT=2314, X 
VOL=SER=SYSRES , DISP=(NEW,KEEP ), X 
DCB=( RECFM=U , BLKSIZE=3625 ) 

//CMDLIB DSN=SYS1.CMDLIB, SPACE=( ABSTR,(20,30,30)),UNIT=2314, X 

// VOL=SER=SYSRES , DISP=( NEW, KEEP), X 


// DCB=( RECFM=U, BLKSIZE=3625 ) 

//SXSCTLG DSN=SYS1.SYSCTLG, SPACE=( ABSTR,(7,53)),UNIT=2314, X 
VOL=SER=SYSRES , DISP=( NEW, KEEP ) 

//SVCLIB DSN=SYS1.SVCLIB, SPACE=( ABSTR,(80,60,75)),UNIT=2314, X 
VOL=SER=SYSRES , DISP=(NEW, KEEP), X 
DCB=( RECFM=U, BLKSIZE=1024 , DSORG=POU ) 
DSN=SYS1.PROCLIB, SPACE=( ABSTR, (20, 140,9)) ,UNIT=2314,X 
VOL=SER=SYSRES , DISP=(NEW,KEEP), X 
DCB=( RECFM=FB , BLKSIZE=400 , LRECL=80 ) 
DSN=SYS1.BRODCAST, SPACE=( ABSTR, ( 20,30) ) ,UNIT=2314, 
VOL=SER=SYSRS2 , DISP=(NEW,KEEP ) 
DSN=SYS1.UADS , SPACE=( ABSTR, (20,53) ) ,UNIT=2314, 
VOL=SER=SYSRS2 , DISP=(NEW,KEEP ), 
DCB=( DSORG=PD , RECFM=FB , BLKSIZE=800 ) 
DSN=SYS1.LOGON, SPACE=( ABSTR,(7,73,5)),UNIT=2314, 
VOL=SER=SYSRS2 ,DISP=(NEW,KEEP ), 
DCB=( RECFM=FB , BLKSIZE=400, LRECL=80 ) 

/ /JOBQUE DSN=SYS1.SYSJOBQE, SPACE=( ABSTR, (60,80), ,CONTIG), 

// VOL=SER=SYSRS2, DISP=(NEW,KEEP ), UNIT=2314 

//LINKLIB DSN=SYS1.LINKLIB, SPACE=(ABSTR,(75,140,100)), 

// VOL=SER=SYSRS2,DISP=(NEW,KEEP ),UNIT=2314, 

// DCB=( RECFM=U , BLKSIZE=3625 ) 





Using TSO Trace 


The TSO Trace Data Set Processor is a problem program that dumps the output data set from TSO 
Trace and produces a formatted listing. Figure 29 shows the job control language required to run 
the TSO Trace Data Set Processor. The example assumes that the TSO Trace Data set has been 
written to a tape volume with a volume serial number of TTRACE. The listing shows the 
parameters specified, and provides an explanation of each entry record as well as the contents of the 
record in hexadecimal and EBCDIC. The contents of register 1 is listed in the third column of the 
Trace Data Set Processor. 


/ /TTRDUMP JOB ,MSGLEVEL=1 
//STEP EXEC PGM=IKJFATRP, PARM='CODES=STD' 


//SYSPRINT DD SYSOUT=A 
/ /TRACEDD DD DSN=TSTRACE, VOL=SCR=TTRACE, UNIT=2400 





Figure 29. Sample Job System to Run TSO Trace Data Set Processor 


TSO TRACE is a started task which operates in its own region. All Driver Entry Codes are 
recorded in buffers which are then written to a data set. This data set can be listed by the TSO 
Trace Data Set Processor or can be analyzed by a user written program. The section of this 
publication Writing Cataloged Procedures for TSO, discusses how to define the TS Trace data set and 
specify parameters required by TSO Trace. Figure 30 shows the format of the TSO Trace data set. 
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When Produced Description of Contents 


"A! When the trace writer is started Word X'FFFFFFFD' 
Word # of 3-word entries per record 
Word Time of Day in timer units 


When the trace writer is stopped. Word X'FFFFFFFE' 
Word Date in packed decimal OOYYDDDS 
Word Time of Day in timer units 


When information was lost (volume Word X'FFFFFFFF' 

switching, low sampling rate, Word Number of entries lost 

etc. Word Time of Day in timer units of 
the first lost entry 


Normal entry (contains words 1-3 Word Bytes 1-2 TJID or 0 


of the DPA). Byte 3 Reserved (X'0O0O' ) 
Byte 4 Entry code 
Word 2 Contents of register 1 on 
entry to TSIP 
Word 3 Time of Day in timer units 


Following a normal entry with Words 1-2 Command name 
entry code O (TMP entry). Word 3 Unpredictable 


Following a normal entry with Bytes 1-7 USERID 
entry code 25 (LOGON establishes Bytes 8-12 Unpredictable 
PSCB ). 


Following a normal entry with Diagnostic data (There will be2+! 

entry code 44 (FE Serviceability) 3-word groups of data available. The value 
of n is contained in bits 5-7 of word 2 
of the normal entry. 





Figure 30. Format of the TS Trace Data Set 


The TSEVENT macro instruction is issued by system tasks to request services of the Driver or to 
notify the Driver of specific events. The TSEVENT macro instruction specifies an event name that 
is translated into a Driver Entry Code. Based on parameters specified to the Driver and on the 
sequence of these codes, the Driver initiates various actions. 


Appendix C lists all the possible event names, the codes they generate, their meanings, and which 
task issues these codes. Associated with most TSEVENT macro calls is a TJID, which identifies the 
user to the Driver. The TJID is assigned when the user logs on. 


The PARM value on the EXEC statement specifies what entries will be listed. All ‘““G” type 
records will be listed regardless of the parameters. The individual keyword parameters should be 
enclosed in apostrophes and separated by commas. The keyword parameters and their syntax are: 


CODES 


specifies which class of entry codes are to be included in the listing. The subparameters, S,T and 
D represent ‘System’ codes, ‘Terminal I/O’ codes, and “Dispatcher” codes, respectively. The 
listing, therefore, will contain only those entry codes belonging to the class, or classes, specified. 
Appendix C lists the Entry Code classes. These subparameters may be written in any order, but 
must not contain delimiters nor embedded blanks. If the CODES parameter is omitted, all 
non-dispatcher entries will be listed, i.e... CODES=ST is the default option. 


TJID=XXX[- YYY] 


specifies that only entries associated with the TJID specified by the number XXX are to be listed. 
If YYY is also given, all entries associated with TJID’s in the range XXX to YYY, inclusive, are 
listed. If the value given for XXX is zero, all entries will be listed. (This is also the default if the 
‘TJID’ parameter is not specified.) Both numbers XXX and YYY must be specified as decimal 
digits. The maximum length of each number is three digits. 
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CLOCK=XXXXXXXX[ - YYYYYYYY] 
indicates that no entry before time XXXXXXXX (relative to the starting time of the first entry) 
is to be included in the listing. If - YYYYYYYY is specified no entry after that time is listed. 
Both numbers must be specified as decimal digits and given the time in seconds. The maximum 
length of each number is seven digits. 


Writing Installation Exits for the Submit Command 


A user exit from the SUBMIT command allows an installation to: 


e Verify a jobname. 

e Verify a userid. 

e Send a message to the terminal and optionally request a reply. 
e Cancel a SUBMIT request. 


The TSO SUBMIT command allows a terminal user to initiate a background job. A description of 
the syntax and use of the SUBMIT command is found in IBM System/360 Operating System: Time 
Sharing Option, Command Language Reference, GC28-6732. 


The SUBMIT command processor writes the contents of a user specified data set consisting of 
Job Control Language statements, (JCL), and input data, onto a logical extension of 
SYS1.SYSJOBQE. The size of this extension is limited at system generation time by the SUBMITQ 
operand of the TSO OPTION macro. Size can be further limited by the SUBMIT parameter which 
the Time Sharing Control Task reads from SYS1.PARMLJIB when the operator issues a START TS 
command. 


Any authorized terminal user can submit a background job, but no jobs will be scheduled if the 
operator has not issued a START BRDR command. 


An installation can control foreground initiated background jobs through an installation written 
SUBMIT exit routine. Through the routine an installation can: 


e Delete, modify, or insert statements. 
« Request that a message be displayed at the terminal and optionally request a reply. 


The routine must be linkage edited as an independent module, given the name IKJEFF10, and 
placed in SYS1.LINKLIB. The SUBMIT command processor invokes the user written exit when the 
first JOB statement is read. The IBM supplied exit does no JCL checking; it only sets the return 
code to zero. Return codes in register 15 control subsequent calls. The return codes are: 


0 - continue -- that is process the current statement and read the next. 

4 - reinvoke the exit routine for another statement -- that is process the current statement and 
re-enter the exit routine when the next statement is read. 

8 - display a message at the terminal and re-enter the exit routine. 

12- display a message at the terminal, obtain a response, and re-enter the exit routine. (If the 
user has specified NOPROMPT, this will cause the SUBMIT processor to issue an error 
message and abort.) 

16- abort. (The exit routine should first use return codes 8 and 12 to issue a message to the 
user.) 

Upon entry to the user written exit routine, register 1 contains the address of a list of six fullwords. 


lst word - address of the current JCL statement. This statement may be changed by the exit 
routine. 


If zero, entry is to get a JCL statement. (The return code from the previous call was 4.) To 
delete the current statement, set this word to zero. 
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2nd word - address of a message to be displayed at the terminal. 


Cc The exit routine obtains a message area and sets this word for return codes 8 or 12. When the 
exit routine is re-entered, it may free the message area. If zero, either there is no message, the 
return code was 0 or 4, or this is the first call. The format of the message is LLtext, where LL is 
a two-byte field containing the length of the message area including the LL field. The maximum 
length is 82. 


3rd word - address of response. 


If the exit return code from the previous call was 12, SUBMIT will free the buffer. The format of 
the response is LLtext where LL is a two byte length field containing the length of the text and 
the LL field, with a maximum length of 82 bytes. 


i 4th word - address of USERID. 
The USERID is 8 characters left justified padded with blanks. 
Sth word - control switches. 
Byte 0 specifies under what conditions SUBMIT will call the exit. 


Byte Bit Meaning 


0 JOB statement 
EXEC statement 
DD statement 
Command 

Null 

Reserved 
Reserved 
Reserved 


The default will cause SUBMIT to enter the exit routine for JOB cards only. The exit routine may 
change the setting of these bits to control when it will be entered. 


C 


“HOF WN - © 


Byte 1 if non-zero contains the card column where the operand field begins. For example, if the 
operand field begins in column 16, byte 1 contains hex 10. 


Byte 2 identifies the current statement. 


Byte Bit Meaning 


operand to be continued 
statement to be continued 
statement continuation 


If bit 5 is on, bit 6 must be on, but bit 6 can be on and bit § off. 


2 O JOB statement 
1 EXEC statement 
2 DD statement 
3 command 
4 null 
5 
6 
7 


Byte 3 is unused. 
6th word - for exit’s use. 


The first time SUBMIT calls the exit, the 6th word is initialized to zeros. The exit can use the 
word for counters or switches. The value is not changed between calls. 
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Writing Installation Exits for the OUTPUT, STATUS, and CANCEL 
Commands 


An installation can write its own exit for the OUTPUT, CANCEL, and STATUS commands. The 
exit routine common to all three command processors is named IKJEFF53, which is a separate load 
module on SYS1.LINKLIB. The IBM-supplied module performs jobname verification if a user exit is 
not supplied. Any STATUS command will be accepted, but the job name for a CANCEL or 
OUTPUT command must equal the userid plus at least one character. The exit routine will not be 
entered for a STATUS command with no operands. The parameters and the return codes have the 
same format and meaning for all three command processors. The installation exit determines which 
command processor is invoking it from a parameter. The parameters are passed through a standard 
linkage with register one containing the address of a list of seven full words. 


Word 1 -- contains the address of the jobname. 

Word 2 -- contains the address of the two-byte length of the jobname. 
Word 3 -- contains the address of the userid. 

Word 4 -- contains the address of the one-byte length of the userid. 


Word 5 -- contains the address of a message to be issued to the terminal user. The format of one 
message is LLtext, where LL is a two byte field containing the length of the entire . 
message including the LL field, with a maximum length of 82 bytes. If 0, the exit is being 
entered to create a message. The exit routine must obtain and free the message area. 


Word 6 -- contains the address of a response from the terminal user. The format of the response is 
LLtext where LL is a two byte field containing the length of the entire message including 
the LL field, with a maximum length of 82 bytes. The caller of the exit routine will 
obtain and free the reply area. 


Word 7 -- contains the address of the one-byte command code. 
Command codes are: 

0 = STATUS command. 

4 = CANCEL command. 

8 = OUTPUT command. 
Return codes are passed in register 15 and are defined as: 

0 = Valid job name, get next job name and continue processing. 


4 = Display message, get response, and call exit again. If the terminal user has specified 
NOPROMPT on his LOGON or PROFILE command, the command will abort and a 
message will be issued to the terminal. 


8 = Display message and call exit again. 


12= Invalid jobname. Cancel request for foreground initiated background service, then continue 
checking any other job name on the command. The exit routine should first use return code 
4 or 8 to issue a message. 


16= Abort. The exit routine should first issue a message. 
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Writing a Logon Pre-Prompt Exit 

A user-written exit, cataloged in SYS1.LINKLIB can specifiy most of the values to be determined 
from the LOGON command or from prompting by the LOGON command processor. These include: 
e The userid. 

e The password. 

e An account character string -- that is the value specified in the ACCT operand. 


e A procedure name -- that is the name of a cataloged procedure usually specified in the PROC 
operand. 


e A region size. 


e A series of 80 byte card images of Job Control Language (JCL) to be used instead of the JOB 
and EXEC statements normally constructed by the LOGON processor. 


e Portions of the Protected Step Control Block. 

e The contents of the User Profile Table. 

e The contents of the Environment Control Table used by the LOGON Prompter. 
In addition, the exit can: 


e Read but not change the Event Control Block which will be posted if the exit terminates due to a 
CANCEL request. 


e Read but not change the completion code from the last step executed from the terminal logging 
on. 


The parameters passed are defined in the PL/I example in Figure 31. The variables declared as 
either BIT or CHAR, VARYING are passed as String Dope Vectors. The exit may be written in 
any language but since parameters are passed as String Dope Vectors, they can be manipulated 
directly in PL/I. For a definition of String Dope Vectors and information on the linkage between 
Assembler Language and PL/I programs, see IBM System/360 Operating System: PL/I-F Programmer’s 
Guide, GC28-6594. The exit must be Linkage Edited and cataloged in SYS1.LINKLIB with a entry 
point name which processes standard Operating System parameters and the module must be named 
IKJEFLD. 


The exit receives control as a problem program and can use the I/O service routines through 
Assembler Language macro instruction (PUTLINE, GETLINE, PUTGET, STAX). 


LOGON passes 16 parameters to the user exit. They are of three types: 
1. Character String defined in PL/I as CHAR VARYING. 

2. Bit Strings defined in PL/I as BIT VARYING. 

3. Fullwords defined in PL/I as BINARY FIXED (31). 


The parameters passed can be given any name in the user written exit procedure but their 
meaning is determined by the order in which they appear. The following explanation of the 
parameters uses the names defined in the PL/I example in Figure 31. 
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CONTROL SWITCHES -- a bit string that specifies what actions the exit has taken. The various 
bit switches are: 


UADS FAIL -- if this bit is equal to one, on entry to the pre-prompt exit, then there was an 
unsuccessful ENQ on the UADS entry for the specified userid. 


REGION FAIL -- if this bit is equal to one on entry to the pre-prompt exit, the region size 
specified in the LOGON REGION operand was too large to be satisfied. The exit can specify 
a different region size. 


FAIL -- if this bit is equal to one on entry to the pre-prompt exit, the LOGON processor will 
cancel the attempted log on. No message will be issued to the terminal user, so the pre-prompt 
exit must issue any needed message. 


CANCEL -- if this bit is equal to one LOGON will terminate and the terminal will be 
disconnected. 


DONT PROMPT -- if this bit is equal to one on return from the procedure, the LOGON 
processor will not prompt the terminal user for any necessary LOGON operand values but will 
use the values specified by the pre-prompt exit. These include: 


e Userid. 

e Password. 

¢« Accounting string. 
e Procedure name. 
e Region size. 


EXIT UADS -- if this bit equals one on return from the pre-prompt exit, the LOGON 
processor will not reference the UADS but will take all character strings and bit strings from 
the procedure. DON’T PROMPT must be set to one if this bit is set to one. 


EXIT JCL -- if this bit is equal to one on return from the pre-prompt exit, the pre-prompt exit 
has supplied Job Control Language (JCL) that is to be used instead of the JOB and EXEC 
statements constructed normally by the LOGON processor. 


EXIT PSCB -- if this bit is equal to one on return from the pre-prompt exit, the LOGON 
processor will use the PSCB accounting string returned by the user but will not write it to the 
UADS at LOGOFF time. 


EXIT ATTRI1 -- if this bit is equal to one on return from the pre-prompt exit, the LOGON 
processor will use the PSCBATR1 string provided by the exit and will not write it into the 
UADS at LOGOFF time. 


EXIT ATTR2 -- if this bit is equal to one on return from the pre-prompt exit, the LOGON 
processor will use the PSCBATR2 string returned by the pre-prompt exit and will not write it 
into the UADS at LOGOFF time. 


EXIT GROUP -- if this bit is equal to one on return from the pre-prompt exit, the LOGON 
processor will use the PSCBGPNM string returned by the exit procedure, but will not write it 
to the UADS at LOGOFF time. 


EXIT UPT -- if this bit is equal to one on exit from the pre-prompt exit, the LOGON 
processor will use the UPT string returned by the exit procedure, but will not be written to the 
UADS at LOGOFF time. 


NO ENQ UADS -- if this bit equals one and the DONT PROMPT and EXIT UADS bits are 
both one, the LOGON processor will not ENQ on the UADS entry for the specified user. 
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If both DONT PROMPT and EXIT UADS are equal to one then: 


C » EXIT PSCB 
» EXIT ATTRI 
» EXIT ATTR2 
» EXIT GROUP 


e EXIT UPT 
also must be equal to one. 
TERMINAL INPUT LINE -- this parameter contains the first line entered from the terminal. 
The values for the next five parameters must be specifed if the DONT PROMPT bit is set to one. 
23 USERID -- used to return a userid to the LOGON processor. 
PASSWORD -- used to return a password to the LOGON processor. 
ACCOUNT -- used to return an accounting string to the LOGON processor. 


PROCEDURE -- used to return the name of a cataloged procedure containing JCL to define the 
resources needed by the terminal job. 


REGION SIZE -- used to return to the LOGON processor a region size for the terminal job. 
The value for the following parameter must be specified if the EXIT JCL bit is set to one. 


JCL -- used to provide Job Control Language statements that define terminal job resources 
( instead of the JOB and EXEC statements constructed by the LOGON processor. 


The next six parameters must have values specified by the pre-prompt exit if EXIT UADS is set to 
one by the pre-prompt exit. 


PSCB -- used by the exit procedure to set a value for the PSCB accounting string. 
FIRST ATTRIBUTE -- used to return a value for the PSCBATR1 string. 
SECOND ATTRIBUTE -- used to return a value for the PSCBATR2 string. 
GENERIC GROUP -- used to return a value for the PSPCBGPNM. 


UPT -- used to return a value for the UPT. 


* ECT -- used to return a value for the Environment Control Table (ECT) used by the LOGON 
prompter. 
” The last two parameters cannot be altered by the pre-prompt exit but may be read. 


ECB -- the Event Control Block (ECB) for the exit procedure. 


COMPLETION CODE -- this fullword contains the completion code for the last job step of the 
last job executed from this terminal. 


For the format of the Protected Step Control Block (PSCB), the User Profile Table (UPT), and the 
Environment Control Table (ECT) see the publication IBM System/360 Operating System: System 
C Control Blocks, GC28-6628. 
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DECLARE 
CONTROL SWITCHES 
UADS FALL BIT 
REGION FAIL BIT 
FAIL BIT 
CANCEL BIT 
DONT PROMPT BIT 
EXIT UADS'- BIT 
EXIT JCL BIT 
EXIT PSCB- BIT 
EXIT ATTR1 BIT 
EXIT ATTR2 BIT 


(*) VARYING, 

DEFINED CONTROL SWITCHES POSITION 

DEFINED CONTROL SWITCHES POSITION 

DEFINED CONTROL SWITCHES POSITION 

DEFINED CONTROL SWITCHES POSITION 

DEFINED CONTROL SWITCHES POSITION 

DEFINED CONTROL SWITCHES POSITION 

DEFINED CONTROL SWITCHES POSITION 

DEFINED CONTROL SWITCHES POSITION 

DEFINED CONTROL SWITCHES POSITION 

DEFINED CONTROL SWITCHES POSITION 
EXIT GROUP BIT DEFINED CONTROL SWITCHES POSITION 
EXIT UPT BIT DEFINED CONTROL SWITCHES POSITION 
NO _ENQ USERID BIT (1) DEFINED CONTROL SWITCHES POSITIO 

DECLARE TERMINAL INPUT LINE CHAR (*) VARYING; 

DECLARE USERID CHAR (*) VARYING; 

DECLARE PASSWORD CHAR (*) VARYING; 

DECLARE ACCOUNT CHAR (*) VARYING; 

DECLARE PROCEDURE CHAR (*) VARYING; 

DECLARE REGION SIZE BINARY FIXED (31); 

DECLARE JCL CHAR (*) VARYING; 

DECLARE PSCB BIT (*) VARYING; 

DECLARE FIRST ATTRIBUTE BIT (*) VARYING; 

DECLARE SECOND ATTRIBUTE BIT (*) VARYING; 

DECLARE GENERIC GROUP VARYING; 

DECLARE UPT BIT 

DECLARE ECT BIT 

DECLARE CP ABEND BIT DEFINED ECT POSITION ( 

DECLARE CP_RETURN-CODE BIT DEFINED ECT POSITION 

DECLARE IO WORD AREA ADDR- BIT DEFINED ECT POSITION 

DECLARE NOSEC_ LEVEL MSG BIT DEFINED ECT POSITION 

DECLARE SEC LEVEL MSG ADDR BIT DEFINED ECT POSITION 

DECLARE COMMAND_ NAME CHAR DEFINED ECT POSITION 

DECLARE SUBCOMMAND NAME CHAR (8) DEFINED ECT POSITION 

DECLARE NO MAIL SWITCH BIT (1) DEFINED ECT POSITION ( 

DECLARE NO NOTICE SWITCH BIT (1) DEFINED ECT POSITION ( 

DECLARE ECB BINARY FIXED (31); 

DECLARE COMPLETION CODE BINARY FIXED (31); 
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Figure 31. Example of PL/I Logon Pre-Prompt Exit DECLARE Statements 
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Storage Estimates 


The estimates included in this chapter are intended for planning purposes only. None of these 
estimates have been verified, and they are subject to change. Verified estimates appear in the 
publication IBM System/360 Operating System: Storage Estimates, GC28-6551 . 


This chapter contains two sections: main storage requirements and auxiliary storage 
considerations. All figures in this chapter are decimal, and “‘K”’ represents a factor of 1024. 


Main Storage Requirements 


The main storage requirement for TSO is divided into four major parts: 
e An addition to the MVT basic fixed requirement. 

e The TCAM Message Control Program requirement. 

e The Time Sharing Control region requirement. 

e The foreground regions in which user’s programs are executed. 


Only the first of these requirements has any effect on the batch environment if time sharing is not 
active. Storage for the TCAM, Time Sharing Control, and foreground regions is obtained from the 
dynamic area when the operator starts time-sharing operations. This storage is returned to the 
dynamic area when time sharing is stopped, and is again available for batch processing. 


MVT Basic Fixed Requirement 


The main storage basic fixed requirement for an MVT system is for: 
e The nucleus. 

e The Master Scheduler Region. 

e The Link Pack Area (LPA). 

e The System Queue Area (SQA). 


Storage for the basic fixed requirement is allocated by the Nucleus Initialization Program (NIP) 
when the system is started and does not normally vary while the system is running. 


Nucleus 
Including TSO at system generation adds approximately 3K to the size of the resident MVT nucleus, 


for a total requirement of about 45K. In addition, communication lines, like other I/O devices, 
require 40 bytes each in the nucleus for control blocks. 


Master Scheduler Region 
The master scheduler region is increased by approximately 4K to handle new or extended operator 


commands for the time-sharing environment, and for extended error recovery. The total requirement 
is about 16K. 
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Link Pack Area 


One small TSO module is added to the required MVT link pack area list of resident modules. The 
minimum link pack area size remains 10K. If the standard MVT resident reenterable load module 
and resident SVC lists are used at system generation, the LPA requirement is about 54K. If space is 
available, an additional 16K of SVC modules for time sharing are appropriate for the resident list, 
for a total LPA size of 70K. 


Additional resident reenterable load modules for time sharing are placed in an extension to the 
link pack area allocated in the Time Sharing Control region, and are resident only when time sharing 
is active. The size of this extension, called the Time Sharing Link Pack Area (TSLPA), is discussed 
with the Time Sharing Control Region requirement. 


System Queue Area 


During time-sharing operations, use of the system queue area is kept to a minimum by placing as 
many control blocks as possible into a local system queue area (LSQA) defined in each foreground 
region. Control blocks in the local SQA are swapped in and out of main storage along with the 
foreground job they apply to. 


Some control blocks associated with foreground jobs, such as queue elements for named data sets 
and operator reply queue elements, must remain in main storage while the job is swapped out. Space 
for these control blocks, and for all control blocks associated with the tasks supervising the 
time-sharing operation must be allocated from the system queue area. These requirements must be 
considered when setting SQA size at system generation or at nucleus initialization. 


Message Control Program Requirement 


The size of the TCAM Message Control Program region depends largely on what options are 
selected and what hardware is present on the teleprocessing network. In addition to the minimum 
requirement for the Message Control Program routines, there are requirements for each defined line 
group, each additional terminal type, and for each permitted user. If teleprocessing applications 
other than TSO are present, additional routines to handle different buffering and queuing techniques 
will be needed. 


In a system with TSO as the only teleprocessing application, with three terminal types and two 
line groups, the Message Control Program requirement is expected to be about 52K plus 800 bytes 
for each possible concurrent user. Although the Message Control Program executes in a problem 
program region, the region may be smaller than the normal minimum problem program region size 
(MINPART). 


Time Sharing Control Region Requirement 


The Time Sharing Control region must provide space for programs for the Time Sharing Control 
Task, Region Control Tasks, several resident SVC routines, the time sharing extension to the link 
pack area, and various control blocks. Some of the control blocks are repeated for each foreground 
region, for each swap data set, or for each time sharing user. An initialization routine brought in 
when the operator starts time sharing analyzes the time-sharing parameters supplied by the 
installation, calculates the region size requirement, and obtains the region from the dynamic area. 


Using a buffer length of 40 bytes, and assuming eight buffers per time-sharing user, a TSO 
configuration with two IBM 2314 swap data sets, one foreground region, and 20 users would 
require a time sharing control region of about 87K. A larger configuration, with two 2301 swap data 
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sets and two 2314 swap data sets, four foreground regions, and 100 users would require about 
117K for the time sharing control region. 


Dynamic Area Requirements 


The SEND operator command, like several others already in the MVT configuration, obtains and 
uses an 12K operator command region from the dynamic area when the operator enters it. This area 
is freed when processing of the command is completed. 


When it is active, the time sharing trace facility requires a 20K region from the dynamic area. 
Foreground Region Requirement 


The foreground region contains the programs invoked by the terminal user. Space must be provided 
in the foreground region for the local system queue area (LSQA) and for four main storage 
subpools used for control blocks for the command system. 


The subpools defined are: 


e Subpool 0--4K. 

e Subpool 1--4K. 

e Subpool 78--2K. 
e Subpool 251--2K. 


The minimum foreground region size is 72K, and all IBM-supplied command processors except some 
of the language processors can execute in this region. 


Auxiliary Storage Requirements 


The major additions to the system auxiliary storage requirements for TSO are for the swap data sets 
and new or larger system libraries and data sets. The installation must also consider the direct access 
storage needs of the individual terminal users, and make allowances for these in the size of the 
system catalog and password data sets. In addition, data sets which are dynamically allocated, use 
SPACE=(50,10,10) for size parameters. 


Swap Data Sets 


A swap data set is divided into swap allocation units, each of which consists of a device-dependent 
number of 2K records. To avoid space fragmentation, space in the swap data set is always assigned 
in integral swap allocation units. Figure 32 shows the sizes of allocation units for various swap 
devices. 


Allocation 
Device Type Unit 


2301 Drum Storage 1 track 
2303 Drum Storage 4 tracks 
2305-1 Fixed Head 

Storage 4 tracks 
2305-2 Fixed Head 

Storage 4 tracks 
2314 Direct Access 

Storage 1/2 cylinder 
3330 Disk Storage 3 tracks 


Figure 32. Swap Allocation Unit Sizes 
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For a system with one foreground region, the maximum necessary swap space can be calculated 
by the algorithm: 


Swap Space = (R/A)e+ (U+2) 
where: 
R is the size of the region. 
A is the size of an allocation unit, as shown in Figure 32, (R/A is rounded up to an integer). 
U is the number of concurrent foreground jobs. 


For instance, a system with one foreground region of 120K, an IBM 2314 swap device, and 30 
possible users would have a maximum swap data set space requirement of: 


(120/64) ¢(30+2) = 232 = 64 allocation units or 32 cylinders 


In this case, the number of allocation units required to hold a complete foreground region is two, 
and the number of users plus two is 32. 


Swap data sets must be allocated by cylinder, even if the swap data set does not occupy a full 
cylinder. 


If TSO runs out of swap space, no message is issued, and the system may loop, so allow 
sufficient space. 


System Libraries and Data Sets 


The additions to system libraries for TSO are expected to be (with the increments expressed in 2311 
tracks): 


e SYS1.LINKLIB--30 tracks. 
e SYS1.SVCLIB--20 tracks. 
e SYS1.MACLIB--60 tracks. 


Two new libraries, SYS1.CMDLIB (command library) and SYS1.HELPLIB (HELP data set), are 
expected to be smaller than 220 IBM 2311 tracks each. 


The size of the User Attribute Data Set, a partitioned data set with a member for each user 
identification, depends on the number of password-identification-account number-procedure name 
combinations defined for each user. A simple identification structure for a single user with a single 
value at each level requires about 200 bytes of storage space. 


Typical time-sharing usage also requires more space for the system catalog and password data 
sets than batch usage. All user data sets are cataloged as a default, and read-only password 
protection is recommended at least for system data sets. This type of protection does not cause any 
performance degradation when the data sets are accessed for reading. 
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Appendix A: TSO Commands 


The commands available to terminal users of the Time Sharing Option are listed below, grouped 
according to function. Installations may give other names to these commands by assigning aliases to 
the respective members in the system command library. No IBM-supplied command names include 
numerals, allowing installations to ensure uniqueness in locally named commands. 


Data Management 


ALLOCATE 
define and allocate a new or old data set. 


ATTRIB 
build a list of data set attributes that can be assigned to data sets being allocated. 


COPY 
duplicate a sequential or partitioned data set, or a member of a partitioned data set, optionally 
modifying such characteristics as blocking factor.! 


DELETE 
delete and uncatalog one or more data sets or members. 


EDIT 
invoke the edit mode or input mode to modify or create a data set; provide an interface to the 
language syntax checkers and processors. 


FORMAT 
format a data set for printing according to embedded controls.! 


FREE 
release a data set or an attribute list. 


LIST 
display at the terminal all or part of one or more data sets, optionally re-arranging information in 
the records.! 


LISTALC 
display at the terminal the names and characteristics of currently active (allocated) data sets. 


LISTBC 
display at the terminal any system notices or messages from other users. 


LISTCAT 
display at the terminal the names and characteristics of a group of data sets indexed together in 
the system catalog. 


LISTDS 
display at the terminal the characteristics of one or more specified data sets. 


MERGE 
copy all or part of one data set or member into another.! 


PROTECT 
assign or modify password protection to a data set. 


1IBM Program Products. 
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RENAME 
change the name of a data set or member, or assign an alias to a member. 


Language Processors 


ASM 
invoke the Assembler (F) prompter.! 


CALC 
invoke the ITF: PL/I processor for desk calculator mode.! 


COBOL 
invoke the Full American National Standard COBOL compiler (Version 3 or 4).1! 


CONVERT 
convert source programs written in Code and Go FORTRAN free form to standard format 
FORTRAN or ITF: PL/I programs to PL/I.1 


FORT 
invoke the FORTRAN (G1) compiler. 


GOFORT 
invoke the Code and Go FORTRAN compiler to compile, load, and execute a source program 
previously saved.! 


PLI 
invoke the PL/I Optimizing compiler.! 


PLIC 
invoke the PL/I Checkout Compiler.1 


RUN BASIC 
invoke the ITF: BASIC compiler and execution control routines.! 


RUN GOFORT 
invoke the Code and Go FORTRAN compiler and execution control routines.! 


RUN IPLI 
invoke the ITF: PL/I compiler and execution control routines.! 


RUN PLI CHECK 
invoke the PL/I Checkout Compiler.! 


RUN PLI OPT 
invoke the PL/I Optimizing Compiler, the OS Loader, and give control to the resulting module.! 


TESTCOB 
invoke COBOL Interactive Debug for monitoring and testing programs compiled under the TEST 
option of the Full American National Standard COBOL Version 4 compiler.! 


TESTFORT 
invoke FORTRAN Interactive Debug for monitoring and testing programs compiled under 
FORTRAN IV (G1) or Code and Go FORTRAN.! 


Program Control 


CALL 
invoke a specified program which exists in load module form. 


1IBM Program Products. 
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LINK 
invoke the Linkage Editor to create a load module from one or more object and load modules. 


LOADGO 
invoke the Loader to process a specified object module, bring it into storage, and give it control. 


RUN 
invoke a user program in source program form, first compiling it, then calling the Loader to bring 
it into storage and give it control. 


TEST 
control the execution of a program, interrupting it at pre-specified points for debugging activity. 
Remote Job Entry 


Note: Use of these commands requires authorization in the user profile. 


CANCEL 
cancel a job previously submitted for background execution. 


OUTPUT 
direct SYSOUT data sets and system messages from submitted jobs to the terminal or a specified 
data set. 


STATUS 
display information at the terminal on the status of a job previously submitted for background 
execution. 


SUBMIT 
submit a data set containing job control language for one or more jobs for interpretation and 
execution in the background. 

System Control 


Note: Use of these commands requires authorization in the user profile. 


ACCOUNT 
add or modify user profiles in the User Attribute Data Set. 


OPERATOR 
invoke the operator mode, allowing the user to enter system commands from his terminal. 
Session Control 


EXEC 
invoke a command procedure. 


HELP 
display at the terminal information on command function and syntax. 


LOGON 
start a terminal session. 


LOGOFF 
end a terminal session. 


PROFILE 
specify special characters for line editing; lock out and accept messages from other users. 


SEND 
direct a message to the system operator or to another user. 
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TERMINAL 
specify the conditions under which an attention interruption is to be simulated, for terminals ‘ 
without attention keys; and define other terminal-dependent characteristics. 


TIME 
display at the terminal the amount of time expended during the current session or the current 


program. 


Command Procedure Definition 


END 
indicate the end of a command procedure. 


PROC 
indicate the beginning of a command procedure; define positional and keyword parameters for 
symbolic substitution. 3 


WHEN 
test the return code set by the previous command in the command procedure (usually CALL or 
LOADGO). 
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Appendix B: Driver Entry Codes 


Entry Code Table (Part 1 of 4) 


[oan nn ns or rr ern I ee enna we 7 
| Event Name | | Input 

| (Entry Code) |Calling Routine (CLASS) |Reason for Entry Register 0 Register 1 | 
aan n nana wn fn nnn fo nnn ~—}-----------7---------------- 
t PMODE (0) |Problem Program (TMP) \comma nd about to be| 0 | Address of 8- | 
| | (S); TIME Command; TEST | processed [ ] character ( 
| | Command | [ | command name. | 
| | | | | | 
| | | | | Bit 0 | 
| | [ | 0O - Ended | 
| | | { 1 - Beginning | 
| | | | 

{TSLICE (1) | Timer Second- Level |Time slice has | NA | NA | 
| |Interrupt Handler (S) | expired | | | 
| | | | | 
|TERMWAIT (2) |TGET/TPUT (T) |User is waiting for | TJID | Bit 0 | 
| | |terminal I/O. Swap | | | 
| | |him out. | | O: input | 
| | | | | 1: output | 
| | | | | | 
| | | | { Bytes 3 and 43| 
| [ | | | number of free| 
| | | | buffers. 

| | | | 

|NIOWAIT (3) |Region Control Task (S) |All user's tasks I TJIID | NA | 
| | {are in non-I/0 | | | 
| | | Wait. | | | 
| | | | | | 
|USERRDY (4) |Dequeue, TIOC |Swapped out user | TJID | NA | 
| | (Attention, TSINPUT, }ready to run. | | 
| {| TSOUTPUT), Timer SLIH, | | | 
| |WTOR (S,T) | | | | 
| | | | | 

| RUSRTRMW (5) |Region Control Task (S) |Restored user is [ TJID | NA | 
| | [still in non-I/0 | j 
| | |wait. Swap him out. | | | 
| | | | 

JREQSTNC (6) |Enqueue (S) |User is setting [ 0 | Estimated must 
| | J[must complete for | | complete time.| 
| | }owned resources. [ | | 
| | | 

|RELMC (7) |Dequeue (S) |User is no longer | 0 | NA | 
] | Jin must complete | | | 
| | |status. | | | 
| | | | | | 
{DISPLAC (8) |TSO Dispatcher (D) JA task switch has | NA | NA 

| | |taken place i | 

| | |resulting in a [ | | 
| | Jbackground task | | 
| | |being dispatched; | | 
| | {the old task was [ | | 
| | [not a background | | | 
| | | task: | | | 
|DISPSYS (9) |TSO Dispatcher (D) JA task switch has | NA | NA | 
| | |taken place | | | 
| | Jresulting ina | | | 
| | |system task being | | [ 
| | |dispatched; the old| | [ 
| [task was not a | | [ 
| | j system task. | | | 
Le a be de_-__- be J 
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Entry Code Table (Part 2 of 4) 


nde rn rn ee en ieee ieee eieiaateeinaieiaa J rr en men mn 
|Event Name [ | | Input l 
[| (Entry Code) |Calling Routine (CLASS) |Reason for Entry |Register 0 Register 1 | 
|------~--~---}----- -------------------}~-----------—------}-----------7-----—-------— 
{[DISPTS (10) |TS Dispatcher (D) [A task switch has 0 NA | 


[taken place | 
| resulting in a | 
jnew time-sharing | 
[task being | 
|\dispatched; the old| 
[task was not for 
|the same TSO user. 


| 
| 
l 
| 
| 
| 
: | 
DISPWAIT (11)|TS Dispatcher (D) JA task switch has | 
| 
| 
| 


| 
| | { 
| | | 
| | { 
| | | 
| | | 
| | | 
| | | 
| | [ | 
| | | NA { NA 
| | |taken place [ | 
| | |resulting ina | | 
| | [system wait. | | 
| | | [ { 
|QSCEST (12) |Region Control Task (S) |Quiesce is started | TJID | NA 
| | | [ i 
JQSCECMP (13) |Region Control Task (S) |Quiesce is complete| TJID | Number of 
| | | | fo | 
|SWOUTST (14) |Time Sharing Control |Swap out started TJID { Byte 0: | 
| |Task (SWAP) (S) [ [ {| Swap units | 
| | | | { Byte 1: _ | 
| | | | | Swap device | 
\ | | | | code (0,4,8,C)| 
| | | | | Bytes 2 and 3:| 
| [ | | | Swap size (in | 
| | | | | 2K blocks) | 
| | | | 
|SWOUTCMP (15)|Time Sharing Control |Swap out complete | TJID | NA 
| ]Task (SWAP) (S) | } | | 
| | | | | 
|SWINST (16) |Time Sharing Control |Swap in started TJID | NA [ 
| |Task (SWAP) (S) | | | [ 
| | | | 
|SWINCMP (17) |Time Sharing Control |Swap in complete | TJID | NA [ 
[ |Task (SWAP) (S) | | j | 
| | | | | 
|RSTORST (18) |Region Control Task (S) |Restore is started I TJID | NA [ 
| | | | | | 
|RSTORCMP (19)|Region Control Task (S) |Restore is complete | TJID ] NA | 
| | | | | 
| (20) | Reserved | | | | 
| | | | l | 
| (21) | Reserved | [ | | 
| | | l | | 
| (22) | Reserved | | | [ 
| | | | | | 
| (23) |Reserved | | j [ 
| | | | | 
| (24) |Reserved | | | [ 
| | | | | | 
JLOGACCT (25) |Logon (S) |Pass Logon | 0 | Address of | 
| | [information for | | accounting 
| | [accounting purposes | | information | 
Lo bee 4 £—— J i 
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Entry Code Table (Part 3 of 4) 


ahaha ee ere nena nn ee em 7 
| Event Name | | | Input | 
\(Entry Code) |Calling Routine (CLASS) |Reason for Entry |Register 0 Register 1 | 
i er i i I 1 
|CHGTOD (26) |Timer SLIH (S) [Time of day must be| 0 | TOD change | 
| | |altered | | value in 52 M | 
| | | | | sec Timer | 
| | | | | units | 
| | | l ; | 
| | | | | Bit 0 | 
| | | | | 0 - positive | 
| | | | | value | 
| | | | | 1 - negative | 
| | | | | value | 
| | Jo | | | 
|SPRGNSZ (27) |Time Sharing Control |Specify region size| | Region number | 
| |Task, Region Control {for specific region | | (Bytes 0 } 
| | Task (S) | | { and 1) ] 
| | | | | Required 
| | | | J region size | 
| | | | | (Bytes 2 | 
| | | } and 3) | 
| | | | ] 
| (28) | Reserved | | | | 
| | | 
|LOGOFF (29) | ind of Task (S) | TJID is to | TJIID } NA 
| | {be released. | | | 
| | |Region can | | | 
| | |be released. [ | | 
| | | 
| LOGON (30) | LOGON (S) | Hook user into | TJID | Region ID | 
| | jregion selected | | | 
| | | by entry code 31 | } 
| | | 
|REQRGNID (31)|Time Sharing Control |Obtain region ID | TJID | Region size 
| |Task, Logon (S) [appropriate to size] [ | 
| | 
[SWINERR (32) |RCT and | | | | 
| |Time Sharing |Swap in failed | TJID | Bit 0 | 
| {Control Task (SWAP) (S) | | | | 
| | | | ] QO: Not LOGON | 
| | | | | image | 
| | | | | 1: LOGON image| 
| | | 
|SWOTERR (33) |Time Sharing Control |Swap out failed. no| TJID | TJID of failed] 
| |Task (SWAP) (S) Jxroom on SWAP data | | user } 
| | |set | | | 
| | | | | 
{TGETPUT (34) |TGET, TPUT (T) |TGET was satisfied; | TJILD | Bit O: 
| | {|TPUT was satisfied | or | 
| | | | 0 | O - TGET | 
| | | | | 1 - TPUT | 
| | l | For TGET, 
| | | | | Bit 1: 
| [ | | | O - all data | 
| | | | | transfered| 
| | | | {| 1 - partial | 
| | | | | transfer | 
| | | | | 
| | | | | Bytes 3 and 4:| 
| | | | | Number of 
| | | | | characters 
| | | | | transferred ] 
L-—-_-_ bo bo a a J 
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Entry Code Table (Part 4 of 4) 


elaine ata eee ore J rn ee mm em “| 
| Event Name | | | Input | 
| (Entry Code) |Calling Routine (CLASS) |Reason for Entry |Register 0 Register 1 | 
|------------- }------------------------ }------------------ +t----------- q----—---------- 4 
| | | | | 
| | | | | | 
| ATTN (35) |TIOC Attention |Attention (not Line| TJID | Sign bit: | 
| |routine (T) | delete) | | | 
| | | | { OO - No exit | 
| | | | | 2 - Exit | 
| | | | | | 
JIOERROR (36) |TIOC Hang Up routine |Pexmanent I/O Error| TJID | NA | 
| | | Terminal | | | 
| | | disconnected | | | 
| | | | { | 
| TERMDSCN (37) | TIOC | Disconnect terminal | TJID | NA | 
| | LOGOFF (T) | logically from TSO | | | 
| | | | | | 
| (38) |Reserved | | | | 
| (39) | Reserved | | [ | 
| | | | | | 
|RGNFAIL (40) |Time Sharing Control [Region failed | NA | Region ID | 
| |Task; Region Control | | | Bit 0 | 
| |Task (S) | | | O - Region | 
| | | | | failed | 
| | | | | 1 - No more | 
| | | | | LOGONS | 
| | | | | for the | 
PE en 
| DONTSWAP (41)| Transient Area {Do not swap out | TJID | NA | 
[ [Handler (S) |user | | | 
| | | | | 
J}OKSWAP (42) |Transient Area [Allow swap out of | TJID | NA | 
| |] Handler (S) | user | | | 
| | | | | | 
|UPDATACC (43)|LOGOFF (S) |Update accounting | TJID | NA y 
| | Jinformation for | | | 
| Juser logging off | ] | 
| | | | | | 
|FEDIAG (44) |Serviceability (S) |FE diagnostics | 0 | Bit OQ; | 
| | [recorded in TSO | | 0 | 
| | TRACE data set [ } Bits 1-4; | 
| | | | | Diagnostic | 
| [ | J) Identifier [ 
| | | | | Bits 5-7: n | 
| | | | {| when 2(nt1) | 
| | | | | equals number | 
| | | | | of entries | 
| | | | | Bits 8-31: | 
| | | | | address of | 
| | | | ] data to be | 
| | | | | recorded. [ 
| | | | | | 
JENQWAIT (45) |Enqueue (S) |User in enqueue | TJID | x*co000000° } 
| | |WAIT. Swap him out. | } | 
bo bee bo a bo J 


Note: On entry to the Time Sharing Driver, register 0 contains: 
Bytes 0 and 1 TJID or 0O 
Byte 2 Reserved 
Byte 3 Entry code 


CLASS refers to the TSO Trace Data Set Processor CODES parameter. 
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Appendix C: Message Control Program Assembly Diagnostic 


IKJ54101I LINEGRP MACRO MUST 


PRECEDE TSOMCP MACRO 


Explanation: Processing of a LINEGRP macro has 
been terminated because it followed a TSOMCP 
macro. All LINEGRP macros must precede the 
TSOMCP macro. 

IKJ541021 MORE THAN 63 LINEGRP 
MACROS 


Explanation: Too many LINEGRP macros were 
issued. The user should check to see if there are 
two or more line groups with the same attributes 
which could be combined into one line group. 
Another possible solution could be combining 1050 
and 2741 line groups into a 5041 line group. 
IKJ541031 REQUIRED OPERANDS) NOT 
SPECIFIED 


Explanation: Processing of this macro has been 
terminated because one or more required operands 
were omitted. 
IKJ54104I1 xxxx INVALID FOR yyyy 
OPERAND 


Explanation: The value (xxxx) of the indicated 
operand (yyyy) is invalid as specified. The user 
should reread the description of this operand and 
determine the permissable values. 

IKJ541051 TRANTAB=xxxx INVALID FOR 
THIS TERMINAL TYPE 


Explanation: The indicated translate table was 
ignored because it is not compatible with the 
terminal type specified in the TERM operand. 
IKJ541061 CODE OPERAND SHOULD BE 
SPECIFIED ONLY IF MORE THAN 
ONE TRANSLATE TABLE IS 
SPECIFIED 


Explanation: The CODE operand has been ignored 
because less than two translate tables are being 
used in the line group. 


IKJ$41071 CODE OPERAND CONTAINS 
MORE THAN 4 SUBLIST 


OPERANDS 


Explanation: Too many suboperands were specified 
in the CODE operand sublist. The user should 
reread the description of this operand to be sure he 
understands dynamic translation. If not, he should 
omit this operand so that the default values will be 
used. 
IKJ541081 CODE SUBOPERAND TOO LONG 
Explanation: Each suboperand of the CODE 
operand must be less than 9 characters. 
IKJ541091 DIAL OPERAND NOT 
CONSISTANT WITH TERM 
OPERAND 


Explanation: The terminal type specified in the 
TERM operand cannot be supported on the type 
of network (switched or non-switched) specified by 
the DIAL operand. 

IKJ541101 xxxx OPERAND OUT OF RANGE, 
DEFAULT VALUE USED 


Explanation: The value of the indicated operand is 
outside the valid limits. The default value has been 
used instead. The user should consult the 
description of this operand to determine the value 
limits and the default value used. 

IKJ541111 xxxx OPERAND CONTAINS TOO 
MANY SUBLIST OPERANDS 


Explanation: The indicated operand was not 
processed because it contained to many sublist 
operands. 
IKJ$41121 SUBLIST OPERAND yy OF 
FEATURE OPERAND IS INVALID 


Explanation: The indicated sublist operand (1, 2, 
or 3) of the FEATURE operand has been ignored 
because it is not valid for the terminal type 
specified in the TERM operand. 
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IKJ54113I1 EBCD OR ASCI (BUT NOT BOTH) 
ALLOWED FOR THIS TERMINAL 


TYPE, DEFAULT VALUE USED 


Explanation: Either EBCD or ASCI, but not both, 
is allowed as TRANSTAB operand for 3270. The 
default value of EBCD is used. 

IKJ541141 xxxx OPERAND NOT ALLOWED 
FOR THIS TERMINAL TYPE 


Explanation: The indicated operand has been 
ignored because it is not allowed with the terminal 
type specified in the TERM operand of the 
LINEGRP macro. 

1KJ54115I TERMNO OPERAND 
REFERENCES NON-EXISTENT 
LINE(S) 


Explanation: ,The TERMNO operand refers to 
more lines than exist for this line group. In other 
words, the number of sublist operands in the 
TERMNO operand is greater than the value of the 
LINENO operand. The extra TERMNO sublist 
operands have been ignored. 

IKJ541161 SCREEN OPERAND MUST BE A 
TWO-OPERAND SUBLIST 


Explanation: The SCREEN operand has been 
ignored because it is not a sublist with two 
suboperands. The default values (12,80)for 2260 or 
(24,80) for 3270 have been assumed. 

IKJ541171 NON-STANDARD SCREEN 
DIMENSIONS -- ACCEPTED 


Explanation: This message is a warning that the 
screen dimensions specified do not correspond to 
standard IBM screen sizes. The values specified 
have been accepted, however. 

1KjJ54118I1 ADDR OPERAND INCORRECT 
LENGTH -- IGNORED 


Explanation: ADDR operand of incorrect length 
has been ignored. For a 1050 terminal the length 
must be two, for 3270 or 2260/65 the length must 
be four. 
IKJ541191 ADDR OPERAND SHOULD BE 
SPECIFIED FOR THIS TERMINAL 
TYPE 


Explanation: The ADDR operand was omitted and 
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the terminal type specified in the TERM operand 
requires addressing characters which can only be 
specified in this LINEGRP macro. Note that this 
warning message cannot be provided in the case of 
2260/65 or 3270 line groups. Omission of the 
ADDR operand can be valid in the LINEGRP 
macros of these line groups since the addressing 
characters may be specified in the LISTTA macro. 
Omission of necessary addressing characters from a 
LISTTA macro will be documented by message 
IKJ54128I. 
IKJ54120I LISTTA MACRO OUT OF ORDER 
-- IGNORED 


Explanation: A LISTTA macro must follow the 
LINEGRP macro to which it refers and precede 
the TSQOMCP macro. 

IKJ54121I1 RLN OPERAND MISSING OR 
INVALID 


‘Explanation: Processing of the LISTTA macro has 


been terminated because the RLN operand is 
missing or invalid. 

IKJ541221 RLN OPERAND REFERS TO 
NON-EXISTENT LINE 


Explanation: Processing of the LISTTA macro has 
been terminated because the value of the RLN 
operand exceeds the value of the LINENO operand 
of the previous LINEGRP macro. 

IKJ$4123I LISTTA MACRO NOT ALLOWED 
WITH TERMINAL TYPE OF 
PREVIOUS LINEGRP 


Explanation: The TERM operand of the previous 
LINEGRP macro specified a terminal type which 
does not permit LISTTA macros to be issued for 
the line group. This LISTTA macro was therefore 
ignored. 
IKJ541241 ADDR OPERAND REFERS TO 
NON-EXISTENT TERMINAL(S) 


Explanation: The number of suboperands in the 
ADDR operand sublist of the LISTTA macro is 
greater than the number of terminals specified or 
defaulted by the TERMNO operand of the 
previous LINEGRP macro. The ADDR operand 
has been ignored. The user should recheck his 
specifications for the ADDR and RLN operands in 


the LISTTA macro and the TERMNO operand in 
the previous LINEGRP macro. 

IKJ54125I MORE THAN ONE TSOMCP 
MACRO CALL ISSUED 


Explanation: Processing of this TSOMCP macro 
was terminated because it was not the first 
TSOMCP macro in the assembly. Only one 
TSOMCP macro call is allowed for each generation 
of an MCP. 
IKJ541261 NO LINEGRP MACRO ISSUED 
BEFORE TSOMCP MACRO 


Explanation: Processing of this macro was 
terminated because no LINEGRP macro had been 
issued previously in the assembly. At least one 
LINEGRP macro must precede the TSOMCP 
macro. 


IKJ$41271 SERIOUS ERROR IN PREVIOUS 
MACRO CALL PREVENTS 


FURTHER GENERATION 


Explanation: One or more serious errors in 
previous LINEGRP or LISTTA macros has 
occurred, causing MCP generation to be bypassed. 
See error messages printed in the listing prior to 
this one. 
IKJ541281 ADDRESSING CHARACTERS 
MISSING OR INVALID FOR 
TERMINAL(S) IN LINE GROUP xx 


Explanation: The TSOMCP macro has discovered 
a terminal whose type requires addressing 
characters, but for which none were correctly 
specified in previous LINEGRP or LISTTA 
macros. The error message indicates the relative 
number (xx) of the line group in which the error 
exists. 
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operand of LISTTA macro instruction 68 
ALLOCATE command 

compiler data sets 39 

function 27 
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CIB 
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CLIST data set 50 
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operand of TSO trace data set processor 94 
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COBOL command 34 
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operand of LINEGRP macro instruction 66 
syntax 
Code and Go FORTRAN 
use 41,36 
CODES 
operand of TSO trace data set processor 93 
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Commands 

adding 22 

format 24 

listed 105-108 

to define work 12 
Command analysis 50 
Command capabilities 20-22 
Command library 

use by Terminal Monitor Program 49 
Command mode 26 
Command name 

definition 24 

use 
Command procedure 

CLIST data set 50 

definition statements 108 

function 31 

handling 50 
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Command processor 
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Compute-bound jobs 60 
Concurrent processing 15 
Conditional statements 

in command procedures 32 
Context editing 27 
Control routines 44 
Conversational Remote Job Entry 

TSO compatible with 15,30 
CONVERT command 

for FORTRAN 36 

for ITF: PL/I 40 
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for TSO dump 74 
for UADS 74 
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Decay constants 
region activity 59 
wait time 49 
DECAYACT driver parameter 84 
DECAYWAIT driver parameter 84 
Default values 
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incommands 24 
Defining a UADS using the TSC procedure 75 
Defining terminals as data sets 
forMCP 64 


| DELETE command 27 
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Assembler 38 


FORTRAN IV (G1) compiler 36 
FORTRAN syntax checker 36 
ITF: BASIC 41 

ITF: PL/I 41 

PL/ I Optimizing Compiler 38 


DIA 
operand of LINEGRP macro instruction 66 
syntax 65 


Dispatcher 45 
DISPLAY operator command 

from terminal 19 
Driver (see Time Sharing Driver) 
Driver entry codes 

(see also TSO Trace Writer) 

defined 109-112 

syntax 109 

used in measuring system performance 107 
Driver Parameters 

operands 84-85 

use 80-81 
DSPCH 

operand of TSC parameters 84 
DTRACE 

as operand of TSOMCP macro instruction 69 

as operator entered TCAM parameter 71 
DUMP 

operand of TSC parameters 84 
Dump 

TSO dump 

ddname for 74 
specifying in TSC START parameters 74 

Dynamic allocation 

commands for 29 

DD statements 17 

function 17 

handling 50 
Dynamic Area 

main storage requirements 103 


EDIT command 
entry modes 26 
for Assembler 38 
for COBOL 34 
for FORTRAN 36 


for PL/I 38 
function 26-27 
Editing 


by context 27 
by line number 27 


Entry modes 
definition 25 
for CALC 38 
for EDIT 26 


Estimated Wait Time Percentage 60 

Even dispatching 60 

EXEC command 30 

EXEC statement 
used to specify background reader 76 
used to specify message control program 73 
used to specify terminal monitor program 77 
used to specify time sharing control task 74 
used to specify TSO trace writer 77 
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FEATURE 
operand on LINEGRP macro instruction 67 
Foreground initiated background (FIB) 
job capability 30,21 
Foreground region 
assignment to 57 
definition 10 
main storage requirement 103 
subpools in 103 
Format control records 
for TEXT data sets 28 
Formatting text 28 
FORMAT command 28 
FORT command 36 
FORTRAN IV 
choice 22 
FORTRAN IV(E) 36 
FORTRAN IV(G1) 36 
options 36 
program entry 36 
testing 36 
FORTRAN IV (G) compiler 36 
FORTRAN IV (H) 36 
FREE command 27 
Free-form source statements 
in Code and Go FORTRAN 41 


GAM 
restriction on 16 

Graphics Access Method (GAM) 
restriction 16 


HALT command (see Starting and Stopping TSO) 
HELP command 
HELP information 32,12 
Hierarchy support 
restriction on 16 


IBMUSER- 75 
IEDQTCAM (see MCP Start Procedure) 
IEFPDSI 74 
IKJACCNT 75 
Initiator 
called by LOGON 47 
INLOCKHI 
operand of buffer control parameters 83 
INLOCKLO 
operand of buffer control parameters 83 
Input editing 
for terminals 25 
Installation exits 
for CANCEL command 96 
for OUTPUT command 96 
for STATUS command 96 
for SUBMIT command 94 
Interaction time 
definition 58 
limit 58 
Interactive Debug 
FORTRAN = 36,22 
COBOL = 34,22 
Interactive programs 
in COBOL 35 
in Code and Go FORTRAN 41 
in ITF: BASIC 40 
inITF: PL/I 40 
in PL/I 38 
Interactive Terminal Facility (see ITF:) 
INTVL 
operand of LINEGRP macro instruction 67 
syntax 65 
I1/O-bound jobs 60 
ITF: 


BASIC 40 
PL/I 40 


Job Control Language 

in LOGON procedure 47,77 
Job definition 

terminal jobs 17 
Job scheduling 

terminal jobs 17,47 


KEYLEN 
operator entered TCAM parameter 70 


Language processors 
ANS COBOL 22 
Assembler 22 
Code and Go FORTRAN 
for program development 22 
FORTRAN (G1) = 22 
invoked by CALL command 
ITF: BASIC 22 
ITF: PL/I 22 
PL/I (F) 22 
PL/I Optimizing Compiler 22 
Line, communication 
non-switched 11 
switched 11 
Line-delete 
character specifying 34 
Line-delete character 
definition 25 
specifying 34 
Line grou 
definition 64 
Line numbering 
for COBOL programs 34 
for data sets 26 
LINEGRP macro instruction 
operands of 65 
used in tailoring an MCP 64-68 
LINENO 
operand of LINEGRP macro instruction 65 
syntax 6 
LINK command 35 
Link Pack Area 
main storage requirement 102 
LINKLIB size 104 
LIST command 29 
LISTCAT command 27 
LISTDS command 27 
LISTTA macro instruction 
operands of 68 
used in tailoring an MCP 63 
LNUNITS 
as operand of TSOMCP macro instruction 69 
as operator entered TCAM parameter 70 
LOADGO command 35 
Local System Queue Area (LSQA) 116 
LOGOFF command 
to end terminal session 32 
LOGON/LOGOFF Scheduler 47 
LOGON cataloged procedure 
defining data sets 77 
naming a terminal monitor program 77 
parameters on EXEC statement 77 
restriction on rollout 77 
sample 
LOGON command 
entry format 24 
example 24 
for identification 25,43 
LOGON pre-prompt 
exit 97 
exit sample DECLARE statements 100 
LOGON procedure 
identifying 24 
invoked by LOGON 47 
job definition 47,44 
LOGON procedure name 
definition 11 
in LOGON command 24 
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Long precision 
in ITF: BASIC 40 
LPA 
operand of TSC parameters 84 


Machine requirements 13 
MACLIB size 104 
Main storage hierarchy 

restriction 16 
Major time slice 

calculation of 57 

definition 57 
MAP 

operand of TSC parameters 84 
Master Scheduler Region 

main storage requirement 102 
MAXSWAP driver parameter 85 
MAXOCCUPANCY driver parameter 85 
MCP 

CSECT name _ 73,69 

region priority 73 

Start procedure 87 

(see also Message Control Program) 
MERGE comman 29 
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